Client Library Documentation

This vanilla javascript library is designed to allow applications such as research tools to easily interact with web services compatible with SHINE, a restful API protocol that allows clients to browse, filter and access a large number of open and licence-protected structured text resources from a wide variety of providers. Please visit the RISE website for more information about SHINE and the RISE project.

rise_client.js is a small open-source library built upon Superagent and uses local storage to store user information. The functions that fetch data from the API return promises, in which the standard HTTP response of the web service is made available. The functionalities are quite basic at the moment, but we welcome pull requests at https://github.com/RISE-MPIWG/rise_js_client.

Contents

Installation

In your HTML file

Using NPM or Yarn

Usage

Initialisation

Authentication

Fetching Text from the SHINE API

Collections

Resources

Collection > Resources

Resource > Sections

Section > Content Units

Pagination & Filters

Contact Info & Feedback

Installation

Load to the library in your HTML file

Link to the rise_client.js file in the header of your html file. Alternatively, if you always want the latest version, you can also link to this file directly from our server at rise.mpiwg-berlin.mpg.de/jslib/rise_client.js. IMPORTANT: You will need to make sure that your host is whitelisted by the SHINE-compatible instance you want to connect to; If you are not sure how to get your host or IP whitelisted, please get in touch with pbelouin@mpiwg-berlin.mpg.de. The most popular RISE instance at the moment is hosted by the Max Planck Institute for the History of Science at rise.mpiwg-berlin.mpg.de.

<script type="text/javascript" src="https://rise.mpiwg-berlin.mpg.de/jslib/rise_client.js"></script>

Using NPM or Yarn

run

npm install rise_client

at the root of your javascript project.

Usage

The library makes the rise object available. This object allows you to perform action on the SHINE-compatible instance of your choice. You first need to initialise this rise object by pointing it to the instance of your choice. Please note that using setRemote() without a parameter defaults to the rise.mpiwg.berlin.mpg.de/api instance URL.

        rise.init.setRemote();
        // default: will point to https://rise.mpiwg-berlin.mpg.de/api

        rise.init.setRemote('https://other.rise.instance/api');
        // will point to the URL of another RISE instance
      

Authentication

Users can sign in using auth.login(). Please note that it is possible to use the API without signing in; In this case, the client will only have access to publicly accessible collections, resources, sections and content units.

        rise.auth.login('user@email.com', 'password')
        .catch(function(error){
          // in case something goes wrong, the error
          // data is made available in the
          // catch function
          console.log(error.response.body);
          console.log(error.status);
        });
      

You can sign out the user by using auth.logout()

        rise.auth.logout()
        .catch(function(error){
          // in case something goes wrong, the error
          // data is made available in the
          // catch function
          console.log(error.response.body);
          console.log(error.status);
        });
      

Please note that it is also possible to authenticate calls to a RISE instance by using the XMLHttp​Request​.with​Credentials property, which will use the active session of the RISE instance you are calling the tool from for authentication. If you are not sure about how to achieve this, please contact Pascal Belouin.

Fetching text from a RISE instance or a SHINE-compatible API

SHINE is a restful API which allows clients to browse, filter and access a large number of open and licence-protected structured text resources from a wide variety of providers. The way the SHINE API models this data is shown in the figure below. This library makes this data accessible through the rise object, which features a number of functions, the most important of which are enumerated below. Calls to rise functions return promises, which make the response object available in the then() callback for example.

Collections

Here is how you can get all the collections the user has access to. An optional filter can be set to filter the collections by name. In the example below, all the collections which have 'optional_filter_string' in their name will be put in the collections variable in the form of an array.

        rise.collections.all({filter: 'optional_filter_setting', page: 1, per_page: 100})
        .then(function(response){
          collections = response.body;
        })
        .catch(function(error){
          // in case something goes wrong, the error
          // data is made available in the
          // catch function
          console.log(error.response.body);
          console.log(error.status);
        });
      

Example: calling

        rise.collections.all({page: 1, per_page: 3})
        .then(function(response){
          collections = response.body;
          document.getElementById("result").innerHTML = JSON.stringify(collections);
        });
      

returns:

          [
            {
            "uuid": "ea637cb7-98de-44dc-8d6b-b55bc97db852",
            "name": "BETAMASAHEFT - Beta maṣāḥǝft Manuscripts",
            "resourceCount": 182
            },
            {
            "uuid": "2c2d5f66-6410-45e5-9bf8-8d0ad2e92149",
            "name": "CBETA - A 金藏",
            "resourceCount": 9
            },
            {
            "uuid": "bc71b08a-4364-4b66-95f5-e8826390d92e",
            "name": "CBETA - B 大藏經補編",
            "resourceCount": 164
            }
          ]
          
          
        

Collection Metadata

You can fetch metadata for a particular collection by using the following:

          rise.collections.matadata('the_collection_uuid')
          .then(function(response){
            resources = response.body;
          })
          .catch(function(error){
            // in case something goes wrong, the error
            // data is made available in the
            // catch function
            console.log(error.response.body);
            console.log(error.status);
          });
        

Example: calling

          rise.collections.metadata('the_collection_uuid')
          .then(function(response){
             resources = response.body;
             document.getElementById("result_col_res").innerHTML = JSON.stringify(resources);
          });
        

returns:

            {
              "dublincore": {
                "language":"zh-Hant",

                ...
              }
              ...
            }
            
          

Collection Resources

You can fetch all the resources for a particular collection by using the following:

        rise.collections.resources('the_collection_uuid',{filter: 'optional_filter_setting'})
        .then(function(response){
          resources = response.body;
        })
        .catch(function(error){
          // in case something goes wrong, the error
          // data is made available in the
          // catch function
          console.log(error.response.body);
          console.log(error.status);
        });
      

Example: calling

        rise.collections.resources(collections[0]['uuid'], {per_page: 2})
        .then(function(response){
           resources = response.body;
           document.getElementById("result_col_res").innerHTML = JSON.stringify(resources);
        });
      

returns:

          [
            {
            "uuid": "b2401d6f-8355-4651-add0-a8d95d6aa75c",
            "name": "B0001 均如大師華嚴學全書",
            "id": 934
            },
            {
            "uuid": "b31c5bab-2cc1-4003-82ba-e6194045adc7",
            "name": "B0002 華嚴經疏論纂要",
            "id": 935
            }
          ]
          
        

Resources

All other functions are used in the same way as described above. Here is how to get all the resources the current user has access to.

        rise.resources.all({filter: 'optional_filter_setting'})
        .then(function(response){
          resources = response.body;
        })
        .catch(function(error){
          // in case something goes wrong, the error
          // data is made available in the
          // catch function
          console.log(error.response.body);
          console.log(error.status);
        });
      

Example: calling

        rise.resources.all({})
        .then(function(response){
           resources = response.body;
           document.getElementById("result_resources").innerHTML = JSON.stringify(resources);
        });
      

returns:

          [
            {
            "uuid": "5cacadbd-eb9c-4bb3-bdea-62f6ca01db35",
            "name": "500 Millions De La Begum",
            "collectionUuid": "9ccd8ea9-1e22-45a5-94c0-901d55465538",
            "uri": "https://rise-rp.mpiwg-berlin.mpg.de/api/resources/6f0570d7-e41a-448e-ad36-a941f6ae53fd"
            },
            {
            "uuid": "598cd218-3989-4b8f-994f-9189f841f784",
            "name": "A1057 新譯大方廣佛華嚴經音義",
            "collectionUuid": "2c2d5f66-6410-45e5-9bf8-8d0ad2e92149",
            "uri": "http://cbdata.dila.edu.tw/v1.2/api/resources/db86ecd1-1f90-48a4-96f0-8f532d770a0b"
            },
            {
            "uuid": "834c25d1-a4cf-4fc9-a3f5-9b13e604c7cf",
            "name": "A1267 大唐開元釋教廣品歷章",
            "collectionUuid": "2c2d5f66-6410-45e5-9bf8-8d0ad2e92149",
            "uri": "http://cbdata.dila.edu.tw/v1.2/api/resources/e486e1dd-0385-4318-8bf2-429ea87a2eab"
            },
            {
            "uuid": "1d905ca2-230a-496d-bcaf-4224c3349cdc",
            "name": "A1490 天聖釋教總錄",
            "collectionUuid": "2c2d5f66-6410-45e5-9bf8-8d0ad2e92149",
            "uri": "http://cbdata.dila.edu.tw/v1.2/api/resources/0122d671-42b0-4482-800e-848d3f9b3482"
            },

            ...
          ]
          
        

Resource Metadata

You can fetch metadata for a particular resource by using the following:

          rise.resources.matadata('the_resource_uuid')
          .then(function(response){
            resources = response.body;
          })
          .catch(function(error){
            // in case something goes wrong, the error
            // data is made available in the
            // catch function
            console.log(error.response.body);
            console.log(error.status);
          });
        

Example: calling

          rise.resources.metadata('the_resource_uuid')
          .then(function(response){
             resources = response.body;
             document.getElementById("result_col_res").innerHTML = JSON.stringify(resources);
          });
        

returns:

            {
              "name": "伊犁總統事略",
              "author": "[祁韻士... et al. 編纂].",
              "level1": null,
              "level2": null,
              "period": null,
              "source": "哈佛燕京珍稀方志庫",
              "volume": "12卷附西陲竹枝詞1卷",
              "dynasty": null,
              "edition": null,
              "bookYear": 1809,
              "language": "zh-Hant",
              "latitude": null,
              "longitude": null,
              "totalPage": 423,
              "editionYear": 0
              }
            
          

Resource Sections

Sections are different from collections, resources or content units as they are hierarchical - section hierarchy is used to represent the structure (chapters, sub-chapters...) of resources such as books for example. As you can see in the response data example below, each Section has a parentUuid field, which can be nil, or be set to the uuid of another section of the same resource.

You can fetch all the sections for a particular resource by using the following:

        rise.resources.sections('the_resource_uuid',{filter: 'optional_filter_setting'})
        .then(function(response){
          sections = response.body;
        })
        .catch(function(error){
          // in case something goes wrong, the error
          // data is made available in the
          // catch function
          console.log(error.response.body);
          console.log(error.status);
        });
      

Example: calling

        rise.resources.sections(resources[0]['uuid'])
        .then(function(response){
           sections = response.body;
           document.getElementById("result_res_sec").innerHTML = JSON.stringify(sections);
        });
      

returns:

          [
            {
            "uuid": "7334edca-5e3a-489d-a68d-90ab750cefe8",
            "name": "A1494 景祐新修法寶錄 第1卷",
            "parentUuid": null,
            "uri": "http://cbdata.dila.edu.tw/v1.2/apisections/6660e65b-9936-4ff7-af13-2f8111452739",
            "contentUnitCount": 23
            },
            {
            "uuid": "6ee459d7-52b5-47ac-b628-32bc8aea7502",
            "name": "A1494 景祐新修法寶錄 第2卷",
            "parentUuid": null,
            "uri": "http://cbdata.dila.edu.tw/v1.2/apisections/9a833ea9-5132-47b7-b744-87a441367fd6",
            "contentUnitCount": 34
            },
            {
            "uuid": "e3d883ce-4b7f-4ebe-831d-5d4deb42a182",
            "name": "A1494 景祐新修法寶錄 第3卷",
            "parentUuid": null,
            "uri": "http://cbdata.dila.edu.tw/v1.2/apisections/8b2a8398-1465-42e4-a396-e124768c2b73",
            "contentUnitCount": 35
          },

          ...
        ]
          
        

Section Content Units

To get all the content units for a particular section, you have to call the following:

        rise.sections.contentUnits('section_uuid')
        .then(function(response){
          content_units = response.body;
        });
      

Example: calling

        rise.sections.contentUnits(sections[0]['uuid'])
        .then(function(response){
           contentUnits = response.body;
           document.getElementById("result_sec_cu").innerHTML = JSON.stringify(contentUnits);
        })
        .catch(function(error){
          // in case something goes wrong, the error
          // data is made available in the
          // catch function
          console.log(error.response.body);
          console.log(error.status);
        });
      

returns:

          [
            {
            "section_id": 79394,
            "name": "A1494 景祐新修法寶錄 第1卷",
            "content": "有大迦葉洎阿那含共綴遺文贊明了義此則經論之所權輿也其後白馬西來蘭臺中閟於是華人識清淨"
            }
          ]
          
        

Section Metadata

You can fetch metadata for a particular section by using the following:

          rise.sections.matadata('the_section_uuid')
          .then(function(response){
            resources = response.body;
          })
          .catch(function(error){
            // in case something goes wrong, the error
            // data is made available in the
            // catch function
            console.log(error.response.body);
            console.log(error.status);
          });
        

Example: calling

          rise.resources.metadata('the_section_uuid')
          .then(function(response){
             resources = response.body;
             document.getElementById("result_col_res").innerHTML = JSON.stringify(resources);
          });
        

returns:

            {
            "name": "伊犁總統事略",
            "author": "[祁韻士... et al. 編纂].",
            "level1": null,
            "level2": null,
            "period": null,
            "source": "哈佛燕京珍稀方志庫",
            "volume": "12卷附西陲竹枝詞1卷",
            "dynasty": null,
            "edition": null,
            "bookYear": 1809,
            "language": "zh-Hant",
            "latitude": null,
            "longitude": null,
            "totalPage": 423,
            "editionYear": 0
            }
            
          

Pagination & Filters

Pagination

The various objects made available by the SHINE API, i.e Collections, Resources, Sections and Content Units are paginated when fetched as lists. After a successful call, the pagination information is returned by the SHINE-compatible instance as variables in the response header, as shown below:

          x-page: 1
          x-per-page: 25
          x-total: 30
        

It is possible to request a particular page, or set the number of objets returned, by setting the page and/or the per_page in the params when calling the function, like so:

          rise.resources.all({page: 1, per_page: 100}).then(function(response){
            resources = response.body;
            // this will return the first page, with 100 resources in the array present in response.body.
          })
          .catch(function(error){
            // in case something goes wrong, the error
            // data is made available in the
            // catch function
            console.log(error.response.body);
            console.log(error.status);
          });
        

Filters

One can also filter the returned objects by their name, by using filter in the params. For example,

          rise.collections.all({filter: 'homer'})
          .then(function(response){
            collections = response.body;
            // this will return all the collections that have the string homer in their name. Please note the results will be paginated as described above.
          })
          .catch(function(error){
            // in case something goes wrong, the error
            // data is made available in the
            // catch function
            console.log(error.response.body);
            console.log(error.status);
          });
        

Feedback, Contact & Participating in the development of rise_client.js

Please contact pbelouin@mpiwg-berlin.mpg.de if you have any questions/comments, discovered a bug, or if you would like to contribute to this library.