How Can We Help?

Getting started: Pure API user guideGetting started: Pure API user guide

Introduction

The Pure API a is also known as 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.

For an overview of the Pure API please visit this introduction from the Pure Conference in Dubrovnik, Croatia 2023

Getting started

Make sure the API is enabled in Administrator > Pure API > Overview
Text says Pure API is enabled. Button can disable it.

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).

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 Access definitions for content and field filtering guide for more in-depth information about this.

Understanding how to work with content

API Documentation. It is strongly recommended getting familiar with the API documenation below:

API Documentation or yourserver.com/ws/api/documentation/index.html
The API Documentation will thoroughly go through key topics as
- Users and roles,
- Synchronisations (API vs XML)
- Synchronisation workaround
- Working with research-output types (and subtypes in general)
- Custom-defined fields
- Files
- Metrics
- and much more.
To that it has a full reference documentation

Testing and first steps

A few guides aimed at new users. These guides will help getting and understanding of how to work with the API.

Examples

More Pure API Information

Resource catalog / Roadmap - Get familiar with what exist and what is coming.
Further inspiration - 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.

Diagram of how API Key helps giving access

Background API Key information

API keys

You access the Pure API by means of an API key. API keys are created, updated, and deleted using the Pure backend application. An endpoint can only be accessed if the current API key is not locked, and is configured to allow access to the endpoint.

Adding the API endpoint /external-organizations/* to the list of allowed endpoints on an API key grants access to endpoints that work with external organizations, such as the /external-organizations endpoint and all endpoints below /external-organizations/.

An API key is often referred to as 'a user API key', as it is associated with a specific Pure user. A Pure API request runs in the context of the user associated with the current API key. The privileges available to the user serve as a baseline; no operation triggered by invoking an endpoint can exceed it. If the user is not allowed to delete a Project, then an attempt at deleting it will fail even if the current API key allows access to an endpoint that deletes Projects. Similarly, an endpoint that returns Projects will only include a Project if the user has permission to read it.

An API key is also associated with an access definition. The access definition of an API key defines what data is accessible when endpoints are invoked, whereas the API key itself defines what endpoints can be invoked. Data access is restricted by applying content filters and field filters.

Read more about how Pure kernel restrictions relates to Pure API restrictions in the Authorization section.

Content filters

✅ Available in 5.22.0 and later

An access definition contains a set of content filters. Content filtering configured on the access definition of the current API key is applied to content returned by endpoints. Some filters are always enabled to maintain the integrity of Pure, and some filters can be modified. For example, to allow access to content that is flagged as not being freely available, the option to 'Filter non-visible content' can be disabled, allowing clients to fetch content that would otherwise only be available on campus, or when using the Pure backend application.

Field filters

✅ Available in 5.22.0 and later

An access definition lists types that operate under the restrictions of API field filtering. API field filtering ensures that a field is only populated if the access definition of the current API key is configured to allow reading it. A field will not be populated if this is not the case. Likewise, a field value is only used for updates to Pure data if the access definition is configured to allow modifications using it. If this is not allowed, the field value specified on an incoming API model object will be silently ignored; it will have no effect on Pure content. It is always allowed to access "get-allowed" endpoint information, regardless of the field filter configuration, as this information is necessary to work with the API endpoint in question.

Metric collection filters

✅ Available in 5.27.1 and later

An access definition allows you to configure access to metric collections for types that supports metrics. Metric collection filtering configured on the access definition of the current API key affects what you get when using metric related operations. Access to metric collections is currently read-only, so you only need to decide what metric collections are available. You can either allow access to all current and future metric collections, or you can restrict access to only include select metric collections.

Read more about metric collections and working with metric collections in the Pure API - Metrics section.

Authorization

Authorization in the Pure API is the act of validating that a request only invokes an operation and only fetches or affects data as permitted by the definition of the API key used for the request. Authorization is applied on multiple levels in the Pure API. Endpoint-level authorization ensures that only operations in endpoints allowed for by the current API key can be used, operation-level authorization ensures that only select kinds of operations are allowed to execute, etc.

Read more about managing and configuring API keys in the API keys section.

Pure kernel restrictions

All applications of Pure run on top of a common Pure kernel. As a result, the Pure API is always limited by the built-in security mechanisms of the Pure kernel. The Pure kernel authorizes access to functionality in Pure based on the currently authenticated user. In the 'admin' Pure application, the currently authenticated user originates from an end-user logging in or a job being configured to run in context of a specific user. In the Pure API, the API key authenticates its associated user for the duration of a request. In effect, a request to the Pure API cannot exceed the bounds of what the user associated with the API key is allowed to do.

Pure logs who does what in the form of audit entries. Each logged audit entry is tagged with the username of the currently authenticated user.

Pure API restrictions

The Pure API supplements the low-level security mechanism of the Pure kernel with a number of ways to further narrow down what is permitted; you cannot configure an API key to allow more than what is possible using its associated user. E.g., if the user associated with an API key cannot delete persons then no part of the Pure API will succeed in deleting persons.

The following table lists the various aspects of the Pure API that can be further locked down using an API key definition and its associated access definition:

Guarded level Determined by Description Example

Endpoint Endpoints allowed for by API key Allow only use of operations in select endpoints. You will be able to invoke GET /research-outputs, but not GET /persons, when /research-outputs/* is the only endpoint added to the current API key.

Operation

Access mode per type on access definition of API key

Allow only use of operations that writes, per endpoint, sub-resources included. Invocation of an operation that writes is allowed if at least one field of the type handled by its endpoint allows Read and write. Generally, operations that require PUT or DELETE require Read and write configured for Access mode.

Invocation of an operation that only reads is not affected by Access mode.

You will be able to invoke GET /organizations, but not PUT /organizations, when the access definition of the current API key has Access mode set to Read-only for name on Organization.

Objects Filtering enabled on access definition of API key Allow only access to objects and details thereof let through by filtering. You will be able to fetch a research output content item with visibility set to FREE, but not one with visibility set to BACKEND, when you use an API key where its access definition has the Filter non-visible content filter enabled.

Fields

Field access allowed for by access definition of API key

Allow only select fields to be read, and only allow values of select fields to be applied during updates. Referred to as "API field filtering".

You will get the abstract, title and uuid fields of a book anthology populated, but not other fields, such as volume, when you use an API key where its access definition has the abstract, title and uuid selected for ResearchOutput under Types and fields.

Filtering enabled using Content filters on access definition of API key Allow only access to fetch field values let through by filtering. You will only get the English abstracts of research output populated if such abstracts have been licensed for external use when you use an API key where its access definition has Filter fields on content with external licensing among its Content filters enabled.

Metrics

Filter access allowed for metric collections by access definition of API key. Access to endpoint of owning object also required.

Allow only selected metric collections to be read.

Read more about working with metric collections in the Metrics section.

You will be able to fetch values of the h-index metric collection using the Person endpoint when you use an API key where its access definition has hIndex selected under Metrics for the Person type.

Updated at January 20, 2025