How Can We Help?
Pure API - Early Access ProgramPure API - Early Access Program
Welcome to the Pure API wiki space, where we can collaborate on the next generation read/write API for Pure.
PLEASE NOTE: the information and data you will have access to through this site can only be used for the stated purposes of this project. Please do not share any of the information or data outside this group unless agreed in writing with Elsevier prior to sharing.
The intention of this space is to provide a forum where we document our current thoughts and stakeholders can provide feedback to our design. While we deeply appreciate constructive feedback, we must balance the solution with both technical limitations and our vision for the future architecture of Pure, so we reserve the right to decide what the "right" decision is in this process.
The wiki space is structured into several sections, namely:
- Pure API scope/vision - a high-level description of our objectives in the problem domain, the intention is that this can guide us in our detailed design
- Use cases - details internally and externally formulated use-cases
- Developer diary - a description of what the team has been focusing on
- User guide - small guides on how to use the Pure API
Pure API scope/vision
Toggle to read more
Accordion BodyThe Pure API provides a secure and complete 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.
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.
Usage of the Pure API in production environment
While the Pure API is still in active development, we consider it production ready from a data integrity and consistency perspective. However, the API still have some points you need to be aware of when using it in the current state:
- It is currently not possible to mark fields as read only when they are managed through the API (like you can do for normal synchronizations).
- The API is not feature complete and does not cover all content types but will gradually be expanded upon.
If the above caveats are acceptable, please go ahead and use the Pure API in your production environment. If you have questions or feedback, please reach out to us.
How to evaluate the progress
At regular intervals, we will deploy a snapshot of the development version of Pure to a sandbox server that is accessible to all Pure API development community members. This will be coupled with a developer diary entry where we describe what is new or changed in the deployed version.
If you have any feedback that is specific to the snapshot we've deployed, please use the comments on the diary entry for the snapshot. Please remember that these represent snapshots in an ongoing development process, so there will rough edges and features that haven't been implemented yet.
The sandbox is a shared environment, so please respect each other's data and configurations.
Interesting sandbox URLs:
https://api.elsevierpure.com/admin/login.xhtml - Sandbox admin login, please contact us (h.kraghhansen@elsevier.com) if you don't have a user
https://api.elsevierpure.com/ws/api/openapi.yaml - OpenAPI 3 specification
https://api.elsevierpure.com/ws/api/ - New API onboarding documentation
https://api.elsevierpure.com/ws/api/api-docs/index.html - Swagger UI for the new API
https://github.com/ElsevierPure/sample-java-api-client - Sample Java client (NOTE: Currently not supported/maintained, only available as a basic intro)
Updated at November 07, 2024