Cochrane REST API

The Cochrane Application Programming Interface (API) is based on Representational state transfer (REST) and uses resource-oriented URLs. The API only supports SSL – any non-SSL calls will return a 403 (FORBIDDEN) return code.

Where possible the API strives to use appropriate HTTP verbs for each action:

...

For the test version of each endpoint, replace api.cochrane.org with test-api.cochrane.org. (documentation at https://test-api.cochrane.org/api-docs/index.html)

Changes

As data in Cochrane evolves so will the API. Changes to the API will be listed on the What's New page. It is possible to sign up for notifications via Email of any changes. We strive to send out notifications as soon as possible for Non-Backward compatible issues to allow clients to update their software. If we are required to release a new API we will support two versions for as long as possible (therefore clients should update their software to the newest version ASAP).

We strive to make as many changes backward compatible as possible. New fields will, if possible, be optional and have default values if not specified.

Current version

The current version of the API is v1. Cochrane REST API uses Accept-headers to store the version information. If omitted, version 1 will be used. Regularly check back here or the swagger documentation to see what is the current version of the API. Request a specific version in the Accept-header as shown in the examples below.

...

JSON will be used as default.

Anchor
Whats new Whats new

What’s New

Nothing to add here yet…

Authentication

OAuth2 is used for authentication. With (almost) each request to an endPoint an OAuth token needs to be provided. The API queries Archie for permissions using the token.

...

If no AuthorizationHeader is sent and Authorization is expected, a 403 (FORBIDDEN) is returned.

If there is no valid AuthorizationHeader and Authorization is expected, a 401 (UNAUTHORIZED) is returned

Requests

The base URL for the Cochrane API is https://api.cochrane.org (and https://test-api.cochrane.org for testing)

Requests can be in many different formats including: JSON, CSV, Smile, XML. The type is defined in the Content-Type-Header. If no Content-Type-Header is defined – JSON is used as a default.

GET – Reading Data

Data from Cochrane can be read by issuing an HTTP GET request to an endpoint. To GET Study 987 for Review 123, send a GET request to: https://api.cochrane.org/reviews/123/studies/987

A successful request will be indicated by a 200 (OK) HTTP status code. The response will contain the data being retrieved (this example in JSON):

...

If an error occurs – it will most often return a 404 (NOT FOUND)

PUT – Writing Data

Update data by issuing a HTTP PUT request to an endpoint. To update Study 987 for Review 123, send a PUT request to: https://api.cochrane.org/reviews/123/studies/987

...

A successful request will be indicated by a 200 (OK) HTTP status. The response will contain the data written (here in JSON):

...

In the case of an error – it will most often return a 404 (NOT FOUND) or 400 (BAD REQUEST)

PATCH – Updating part of the data

To partially update a record issue a PATCH request to an endpoint. To partially update Study 987 for Review 123, send a PATCH request to: https://api.cochrane.org/reviews/123/studies/987

...

NB: It is NOT possible to send default values (Null, 0, false, etc) using the PATCH request. All fields containing default values will be ignored. In the case where a field needs to be updated with a default value – use PUT.

POST – Creating Data

Create a new record with a POST request to an endpoint. To create a new Study for Review 123, POST a request to: https://api.cochrane.org/reviews/123/studies

...

In the case of an error – it will most often return a 400 (BAD REQUEST).

NB: Use POST with client provided ID’s (only a few endPoints support client provided ID's)

DELETE – Removing Data

Delete data with a DELETE request. To delete Study 4568108645260278276 for Review 123, send a DELETE request to: https://api.cochrane.org/reviews/123/studies/4568108645260278276

A successful delete request will be indicated by a 204 (OK) status code with an empty response. If an error occurs it will most likely be a 404 (NOT FOUND).

OPTIONS - endPoint information

OPTIONS is available on all endPoints. It is mainly implemented for the purpose of CORS (Cross-origin resource sharing). When sending an OPTIONS to any andPoint a 200 (OK) will be returned with the following headers:

...

• Access-Control-Allow-Origin - returns a list of sources that can access the API. Currently accessable by all ("*" is returned)
• Access-Control-Allow-Headers - returns a list of headers allowed. Currently returning: Authorization, Content-Type, Accept, If-None-Match, If-Modified-Since
• Access-Control-Allow-Methods - returns a list of REST methods allowed for the specific endPoint. This is a comma separated list, eg: OPTIONS,GET,POST,PUT,PATCH,DELETE. Depending on the endPoint, 1-6 methods will be listed
• Access-Control-Max-Age - returns number of seconds the response should cache values (current default value is 3600)
• Access-Control-Expose-Headers - returns a list of exposed headers. Currently returning: Content-Type, Cache-Control, Link, Total-Count, ETag

Rate Limiting

For all requests a Rate-Limit might be inserted in the future. If your Rate-Limit has been reached (the maximum number of requests per minute/hour) a 429 (TOO MANY REQUESTS) response will be returned. In this case try again after a short while.

Conditional requests

All responses return an ETag-header. Almost all responses also return a Last-Modified-header. You can use the values of these headers to make subsequent GET requests to those resources using the If-None-Match and If-Modified-Since-headers, respectively. If the resource has not changed, the server will return a 304 (NOT MODIFIED).

NB: making a conditional request and receiving a 304 (NOT MODIFIED) response does not count against your Rate Limit, so we encourage you to use it whenever possible. This will help on server loads.

Language

The language is specified in the request header by using the Accept-language header. If not specified, the default language is the default language of the request. Currently only English is supported. Accept-language is primarily for error messages

...

In the above example, the error message will be supplied in Danish if available. In the case where the language is not supported – English will be used.

Parameters

The Cochrane REST API accepts the following additional query parameters and values. URL query-string parameters are used for filtering – not for resource names.

Download

If you would like to trigger a file download of your data from a web browser, add download=XXX. This will cause the REST service to add the appropriate headers so that browsers know to save the data to a file (called ‘XXX’).

...

The above example will request for the author 333 and trigger a download in the browser. The format of the file (the response) is set in the Accept-Type header.

...

If the download parameter is used in a GET request with the ETag matching – the download parameter will supersede the 304 (NOT MODIFIED) and trigger a download even though the data has not been changed – thus resulting in a 2XX status code.

Envelope

envelope=true – In some situations it is necessary to have the http status codes enveloped inside the result. If set the result will be enveloped with HTTP result code, status, a message and the result wrapped in a data element:

• code – contains the HTTP response status code as an integer.
• status – contains the text: “success”, “fail”, or “error”. Where “fail” is for HTTP status response values from 500-599, “error” is for statuses 400-499, and “success” is for everything else (e.g. 1XX, 2XX and 3XX responses).
• message – only used for “fail” and “error” statuses to contain the error message in English. If Accept-Language header is set and language is supported the error message will be supplied in the requested language.
• data – contains the response body. In the case of “error” or “fail” statuses, this contains the cause, or exception name.

...

    "dataSource": "PUB",

    "noteId": 0

  }

}

EdgedTitleLinks

When requesting for collections of items which don't fit within a paged result it is nice to know the boundaries for other pages. Eg. when you request for page 15 in a list of Studies for a review, the result is the Studies on that page. When turning edgedTitleLinks on (edgedTitleLinks=true) all other generated link-header-pages will contain (in their title) the boundaries: "From which Study - to which Study" does the page contain. So if getting all Studies for a review results in 20 pages, the current page is 15 and the pages requested (see pages under the pagination section) is -2,-1,1,2 then the result could look something like this (only displaying link headers):

...

<https://api.cochrane.org/reviews/123/studies?page=17>; rel="2"; page="17"; title="Mazeh 2006 - Moore 1980"

Excluded

excluded=id,name,… As an optimization, you can specify which fields not to return. Field names are separated by a comma.

...

NB: It is not possible to use the excluded parameter in combination with Review Database API Included. If both query parameters are used an error will 400 (BAD REQUEST) will be returned.

NBB: As a default versionStart, versionEnd, createdBy, deletedBy and versionNo are excluded from every result. If these fields are required then provide an empty excluded (https://api.cochrane.org/reviews/123/studies/987?excluded).

Expand

Many endpoints support expanding the related resources to minimize the required number of API round trips. It is used by supplying a comma separated list of Resources. Each Resource lists other Resources that are expandable.

...

NB: Please keep in mind that this can be a very CPU and bandwidth intensive feature - use with care. Once Rate Limiting is implemented - use of Expand will be an expensive call.

Nested Expand

It is allowed to make nested expands:

...

In the above example all referenceIdentifiers to the references will be expanded (and returned) within the references (which is returned within the Studies). There is no limit to the number/levels of expands.

sort

Within an expand it is also possible to sort the result:

...

The above example will sort the reference-list within each Study by name. Sorting in expand uses the same rules as sorting for collection results.

filter

Within an expand it is also possible to filter the result:

...

The above example will only return expanded references on Studies for review 123 that contain the String "hello". Filtering in expand uses the same rules a filtering for collection results.

expand

It is further possible to expand an expanded result - see Review Database API Expand.

expandAll

It is possible at any point to use expandAll to expand recursively - see Review Database API ExpandAll.

hideEmptyList

In order not to send empty result-lists - it is possible to set hideEmptyList=true - this will prevent empty lists from being sent.

ExpandAll

ExpandAll is a shortcut in order to expand everything on a Resource. In order not to create circular expands cirtain limitations are inserted when using ExpandAll. When expandAll is used without a value - all fields below the resource is recursively expanded. In order just to expand a list of fields this can be done by writing a comma separated list of fieldNames:

...

It is possible to further manipulate the expandAll result, append a '[' and ']' to the end of the field just like Review Database API Expand.

Hal

Turn hal on (=true) or off (=false). This query parameter will supersede the Accept-header. If turned on the result will include hal information.

Included

included=id,name,… As an optimization, you can specify which fields to return. Field names are separated by a comma.

...

NB: It is not possible to use the included parameter in combination with Excluded.

Metadata

Only used for requests that return a collection. For all requests (GET, PUT, PATCH, POST and DELETE) it sends the total_count – which is the number of items returned.

...

    "pages": 1,

    "total_count": 2

}

Pagination

A GET request that returns a collection will be set to 30 items per page by default. (The maximum number of items per page is 100). If a different number of items per page is required – use the per_page query parameter. Use the page parameter to specify the page wanted. Use the pages parameter to create user defined Link-headers.

The page numbering is 1-based and omitting the page parameter would result in the first page. If no pagination is specified and the result is bigger than the number of items per page (30 items if nothing is specified) a 206 (PARTIAL CONTENT) will be returned. A 206 (PARTIAL CONTENT) will also be returned if the requested page and per_page cannot be fulfilled (in case you request the last page and it does not contain enough items to fill the per_page specified).

...

pages=-2,-1,1,2 - would create Link-headers for pages -2, -1, 1 and 2 relative to the current page. pages supports ranges. In order to specify a range write: [xxx TO yyy]. In this case Links to pages xxx to page yyy will be generated. xxx must be smaller than yyy otherwise a 400 (BAD REQUEST) will be thrown. A combination of ranges and single pages is supported: pages=-10,[-5 TO 5],10

In all collection results a response header: Total-count is added containing the total number of items in the result.

Link Header

The pagination info is included in the Link-header. Use these links instead of creating your own.

...

Link-headers are added if available. On non-collection results – a title will be provided with the “self” link.

Print

print=pretty - If you’re debugging your application, you may find it useful to view the data in a human-readable format.

...

print=silent - As an optimization you can add print=silent to suppress the output from the server when writing data. The response will be empty and indicated by a 204 (NO CONTENT) if successful.

https://api.cochrane.org/reviews/123/studies/987?print=silent

Anchor
Filter Filter

Filter

It is possible to filter a collection result further. To do this use q=. q= supports different kinds of filters:

...

NB: Use this option with caution as it is NOT a database search. The collection returned is sequentially filtered by looking at each field in each item in the collection. Once Rate Limiting is implemented - use of Filter will be an expensive call.

Anchor
Sort Sort

Sort

It is possible to sort a collection of results. When sorting is required, specify a comma separated list of field names to sort by. If a “-“ is used before the field name the collection is sorted in descending order.

...

This would get all OutcomeAnalysis for review 123 and sort them on the name provided in the expanded outcome.

Responses

The default encoding for responses is HAL+JSON. If a different encoding is wanted, it must be specified in the Accept-header. The following types are accepted:

...

If multiple Accept-headers are in the response – the API will prioritize the Accept-header closest to the top of the above list.

HAL

HAL (or HyperMedia Application Language) provides a set of conventions for expressing hyperlinks in either JSON or XML.

...

            "title": "HHL"

        }

}

Etc…

HTTP Status Codes

Cochrane uses conventional HTTP response codes whenever possible to indicate success or failure of an API request.

Success codes

Error codes

Entry Points

All endPoints are documented in Swagger on the following url:

...