SHINE API

SHINE allows researchers and research tools to access a wide range of full text resources from a range of providers in a standard and unified way.

The RISE Project encourages and supports third-party development of applications and software modules based on SHINE. The more ‘plug-and-play’ use cases we have, the more robust the research infrastructure becomes!

To demonstrate the benefits of working with RISE and to encourage third-party development of SHINE -compatible technical solutions, a suite of open-source toolkits is available for others to adopt and adapt for their own purposes. They can be found on the RISE Project's Github page. RISE-RP is a reference implementation for resource providers to publish their resources via SHINE. RISE-JS is a JavaScript library for research tool developers to enable their research tools’ resource consumption via SHINE. RISE-Catalog is a browser client that research organizations could customize and implement to facilitate resource discovery and resource-tool linkage for their researchers.

API Data Structure

The SHINE API structure is as follows: Resources (such as a book for example) belong to a Collection. Resources have Sections, which can have a parent or not. Sections are used to represent chapters and sub-chapters; If a section has no parent, it is considered a root section. Finally, Content Units are the units of text and belong to a section. Metadata can be stored and accessed against each object of the hierarchy to describe the language, rights and other attributes in the form of a JSON Object.

The SHINE API also provides endpoints for users to build their own collection of resources, which we call "Corpus". The mechanisms through which resources can be added or removed from a corpus are detailed in the OpenAPI documentation provided below. In addition, further endpoints are provided to get the list of Research Tools currently supported by the RISE Middleware instance, as well as for sign in and sign out. Please note that although we do support authentication using a RISE-API-TOKEN placed in the header, it is also possible to use the API With a valid RISE Session through the use of the XMLHttpRequest.withCredentials property.

Please find below the SHINE API documentation in the OpenAPI standard. If you are not familiar with this API definition standard, please refer to its documentation for more information.

Metadata Structure

The SHINE Metadata structure consists of four different namespaces, allowing for the flexible representation of any type of metadata that can be associated with Collections, Resources, Sections and Content Units. A typical metadata object at the resource level would therefore look as follows:

{
  dublincore: {
    title: 'The Odyssey',
    date: '1932',
    creator: 'Homer',
    edition: 'Original Edition'

  },
  shine: {
    resource_type: 'book',
    section_type: 'page',
    content_unit_type: 'line'
  },
  extra: {
    anything: 'extra'
  }
}

In addition, the RISE team strives to make its content JSON-LD compatible. Thus, an fourth additional @context namespace is automatically added to resources served by this RISE middleware instance, and looks as follows:

@context: {
  '@vocab' => 'https://rise.mpiwg-berlin.mpg.de/pages/doc_for_developers',
  dublincore: 'http://dublincore.org/specifications/dublin-core/dcmi-terms/2012-06-14/?v=terms',
  shine: 'https://rise.mpiwg-berlin.mpg.de/pages/doc_for_developers#shine_metadata'
}

Please find below the SHINE API documentation in the OpenAPI standard. If you are not familiar with this API definition standard, please refer to its documentation for more information.

SHINE's standard API mapper requires resource providers to implement a minimal set of API endpoints to make their resources available. Resources are protected by the RISE-API-TOKEN authorization header. This token mechanism allows resource providers to limit and monitor access to their resources.