Cristin REST API

Introduction

The Cristin REST API allows you to interact with our system programmatically from your own application. Using the API you interact with resources such as

  • Projects
  • Biobanks
  • Institutions
  • Persons
  • Results
  • Units

The API attempts to conform to the RESTful design principles. You interact with the resources exposed via the API by accessing resource collection and element URIs using the HTTP verbs (GET, POST, and PATCH).

Data transfer is secured using HTTPS.

The API accepts and returns JSON data via the API.

The API supports Cross-origin resource sharing (CORS) for GET requests.

Versions

Current version

The current version is 2.6 accessible at api.cristin.no/v2/.

The latest version will also always be accessible at api.cristin.no/latest/.

For details, see the release notes.

Previous versions

When a major version is released the previous version will be in operation for a certain period of time.

Version 1 is terminated from 25.02.2019

Versioning strategy

API versioning is implemented by embeddig the major version number in the API URLs.

Given a version number MAJOR.MINOR.PATCH, we increment the...

  • MAJOR version when we make incompatible API changes,
  • MINOR version when we add functionality in a backwards-compatible manner, and
  • PATCH version when we make backwards-compatible bug fixes.

Each element increases numerically. For instance: 1.9.0 -> 1.9.1 -> 2.0.

The full, current version number can be found at api.cristin.no/latest/build-info.

HTTP Verbs

HTTP methods (sometimes referred to as verbs) indicate the desired action to be performed on the identified resource:

Verb Description
GET Retrieves a resource.
POST Creates a resource.
PATCH Performs a (partial) update of a resource.
PUT Creates a new resource or replaces a representation of the target resource with the request payload.

HTTP Response Codes

Code HTTP Definition Description
200 Ok The request was successful.
201 Created The POST request was successful. The response contains the saved object.
204 No Content The PATCH request was successful. We return an empty body after a successful PATCH.
307 Returns the Content Temporary redirect
400 Bad request The parameters or contents of the request are invalid. Correct your input and try again.
401 Unauthorized The request requires authentication. You must provide valid credentials.
403 Forbidden Your credentials may be valid, but you are not authorized to perform this request.
404 Not found The requested resource was not found.
500 Internal server error An internal error occurred while processing request. Please try again.
503 Service unavailable Maintenance is being performed. Please try again later.

Search Guidelines

Several resources allow searching for objects by filter parameters. Parameters are combined by boolean conjunction ("AND"), i.e. only objects matching all criteria are returned.

Authentication

Read access (GET) to the Cristin REST API does not require authentication, but authentication can be supplied to some GET services to retrieve additional, unpublished objects. This uses HTTP Basic authentication.

Write access (POST, PATCH and PUT) is only available to Cristin's cooperation partners and is protected using HTTP Basic authentication.