Pure API user guide
Introduction
The Pure API is a Write API or CRUD (Create, Read, Update, Delete) API and is a powerful way of both extracting data and write data directly into Pure.
The Pure API provides a secure web services API for using and managing research information data in Pure. The API enables a broad range of use-cases for interacting with research information, from anonymous Open Data scenarios to enabling the next generation Pure admin.
Getting started
Make sure the API is enabled in Administrator > Pure API > Overview
Access definition
It is strongly recommended to create an Access Definition as the first step and then combine it with the User. This will be used with an API Key to gain access to relevant content for relevant users.
The access definition decides the types of content and the fields on each content that can be accessed, and if access should be read only or be able to update. It also sets the filters on the content (e.g. do you have access to backend-only content or only content with FREE visibility).
Please follow the Access definitions for content and field filtering guide for more in-depth information about this.
API Key
Afterwards you need to create an API key. This defines which of the available endpoints the key can use, and to which User the access is given.
Paring an Access Definition with an API key then defines the what a User with access to Pure content can do with it.
Please follow the Pure API: Access definitions for content and field filtering guide for more in-depth information about this.
Understanding how to work with content |
Testing and first steps |
|
API Documentation. It is strongly recommended getting familiar with the API documenation below:
|
A few guides aimed at new users. These guides will help getting an understanding of how to work with the API. |
Examples |
More Pure API Information |
|
Disclaimer: Proceed at your own risk; these examples are provided solely for reference and may be used for your intended purposes. It is recommended to run them in a test-staging environment to assess the outcome and understand their functionality. Elsevier will not support or review any code that uses or is based on these examples.
Examples that offers API users guidance on retrieving and analyzing Pure data compared with report examples: |
Get familiar with what exist and what is coming:
Learn how others have benefitted from the Pure API |
Background information
To cater to this broad spectrum of use cases, the Pure API is implemented as a REST API, conceptually exposing the Pure model as a graph of interconnected, self-contained resources. Depending on the configured permission and sharing model, a service user interacts with the resources using standard HTTP methods (GET, PUT, PATCH, DELETE) a commonly used model with well-defined semantics. The intention of this choice is to reduce the friction for new service users, enabling them to quickly and safely be able to implement their use-case on top of the Pure API.
The API specification is defined and published as an OpenAPI 3 specification, enabling service users to quickly generate a client while at the same time providing developers with useful documentation on the API and its semantics. As the API evolves naturally over time, we use the contract to ensure that we remain backward compatible and only in extreme cases introduce a new version of an endpoint, this should minimize the necessary maintenance burden of properly implemented clients. To ensure that older clients do not unintentionally delete parts of the entity representations when interfacing with newer server API's, all PUT requests will transparently apply JSON merge patch (RFC7386) semantics.
To guarantee authorized access and management of Pure resources all API requests are performed in the context of a defined user, whether this is a researcher managing their output authenticated by the institution SSO and authorized by Pure, read-only access of only public data as an anonymous user or a locally developed integration component using the Pure API with a system user. Configuring a sharing context appropriate for a specific use-case not only involves coupling the requests to a specific user, but also whether there are further content-type or action restrictions and whether there are any field-level restrictions.
