Page History

RETIREMENT NOTICE. This API will be retired along with Archie. It will be replaced by the Archive API:

Jira

server	JIRA
serverId	84faf8a3-76e6-3cf7-862e-a59f68644f2d
key	CIT-1808

System	Endpoint	Usecase
RevMan (front end)	/rest/reviews/<id>/metadata	Multiple CRGs
ReviewDB	/rest/reviews (with params)	My Reviews
Translate	/rest/reviews /rest/reviews/<id>/versions /rest/reviews/<id>/<version>/translations	Determine translation status
EPPI? 20.160.135.113	/rest/reviews?myRole=Author&published=false	?
CRS? 86.188.140.214	/rest/reviews?published=false&status=A&groupId=LIVER	?

Endpoints

All endpoints require a secure connection (HTTPS). If a plain HTTP connection is attempted an error status code 403 (forbidden) is returned.

Authentication must be provided as either HTTP Basic authentication or as Bearer authentication using an OAuth 2.0 access token. If authentication is missing an error status code 401 (unauthorized) is returned.

Possible error codes are:

400 (bad request): If there is a problem with syntax of the request.
401 (unauthorized): If authentication is missing or incorrect.
403 (forbidden): If the user is not authorized to access the review, if the connection is not secure, or if the user is denied access for other reasons than authentication.
404 (not found): If no review with the given ID exists.
409 (conflict): In case of a check in/out conflict, e.g. if a user tries to check out a review that another user has checked out already.
500 (internal server error): In case of an unexpected problem on the server.

For the test version of each endpoint, replace archie.cochrane.org with test-archie.cochrane.org.

Encoding of response

You can specify an Accept header to control the returned encoding, e.g:

Accept header	Description
application/xml;charset=iso-8859-1	Review in rm5 format, iso-8859-1 charset
application/xml;charset=utf-8	Review in rm5 format, utf-8 charset
application/x-jats+xml;charset=utf-8	Review in JATS format, utf-8 charset
application/x-dar+zip	Download JATS package

If you don't specify an Accept header the behaviour of this API is undefined (i.e. you may get any of the above content types or encodings).

Getting a review

Returned MIME type is dependent on the specified Accept header. The response body contains the review in the specified format.

Last published version using CD number

GET

This page describes the basic REST API for working with reviews stored in Archie. This API is interfacing with Archie's XML review document store and is therefore also XML based and works on whole reviews (in RM5 format).

A more granular API, where review sections can be accessed individually, is being designed to interface with the new review database. The new API is expected to replace this API at some point.

Table of Contents

Endpoints

All endpoints require a secure connection (HTTPS). If a plain HTTP connection is attempted an error status code 403 (forbidden) is returned.

Authentication must be provided as either HTTP Basic authentication or as Bearer authentication using an OAuth 2.0 access token. If authentication is missing an error status code 401 (unauthorized) is returned.

Possible error codes are:

400 (bad request): If there is a problem with syntax of the request.
401 (unauthorized): If authentication is missing or incorrect.
403 (forbidden): If the user is not authorized to access the review, if the connection is not secure, or if the user is denied access for other reasons than authentication.
404 (not found): If no review with the given ID exists.
409 (conflict): In case of a check in/out conflict, e.g. if a user tries to check out a review that another user has checked out already.
500 (internal server error): In case of an unexpected problem on the server.

For the test version of each endpoint, replace archie.cochrane.org with test-archie.cochrane.org.

Encoding of response

You can specify an Accept header to control the returned encoding, e.g:

Accept: application/xml;charset=iso-8859-1
or
Accept: application/xml;charset=utf-8

If you don't specify an Accept header you must be able to deal with either encoding.

Getting a review

Returned MIME type is "application/xml". The response body contains the review in XML format.

Last published version using CD number

GET https://archie.cochrane.org/rest/reviews/{CD Number}

Example:

GET https://archie.cochrane.org/rest/reviews/CD000004

Last published version using Review ID

GET https://archie.cochrane.org/rest/reviews/{Review ID}

Example:

GET https://archie.cochrane.org/rest/reviews/047199081020060395

Latest version using Review ID

GET https://archie.cochrane.org/rest/reviews/{Review ID}/latest

Example:

GET https://archie.cochrane.org/rest/reviews/047199081020060395/latest

Specific version using Review ID

GET https://archie.cochrane.org/rest/reviews/{Review ID}/{Version}

Example:

GET https://archie.cochrane.org/rest/reviews/047199081020060395/7.0

Checking a review out

Returned MIME type is "application/xml".

PUT https://archie.cochrane.org/rest/reviews/{Review IDCD Number}/latest

The body of the request should be empty.

Example:

PUT GET https://archie.cochrane.org/rest/reviews/047199081020060395/latest

The response body contains the review in XML format.

Note: this is a PUT request since it is changing the state of the review.

Checking a review in

Returned MIME type is "application/json".

CD000004

Last published version using Review ID

GET https://archie.cochrane.org/rest/reviews/{Review ID}

Example:

GET https://archie.cochrane.org/rest/reviews/047199081020060395

Latest version using Review ID

PUT GET https://archie.cochrane.org/rest/reviews/{Review ID}?tag={version description}

The review in XML (RM5) format must be provided in the body of the request.

The response body contains a plain text report from the check-in.

Example

/latest

Example:

PUT GET https://archie.cochrane.org/rest/reviews/047199081020060395?tag=New%20studies%20added

Undoing a check-out

/latest

Specific version using Review ID

GET PUT https://archie.cochrane.org/rest/reviews/{Review ID ID}/latest/undo

The body of the request should be empty.

The response body will be empty.

Example

{Version}

Example:

GET PUT https://archie.cochrane.org/rest/reviews/047199081020060395/latest/undo7.0

Getting

...

review translations

List translations of the latest published version using Review ID

GET https://archie.cochrane.org/rest/reviews/{Review ID}/translations

ExampleThe base request for getting a list of reviews is:

GET https://archie.cochrane.org/rest/reviews

This will return all published reviews in Archie, so for most purposes a filter based on XPath or additional query parameters is required.

The response is an XML document listing the key attributes and properties of each review, and a link for accessing the full review, e.g.:

<reviews count="15">

/047199081020060395/translations

The response is a list of published translations of the latest published version of the review as a JSON array:

Code Block

language	js
collapse	true

[
  {
    "language": "fr",
    "title": "Décompression abdominale en cas de suspicion d'une souffrance fœtale/pré-éclampsie",
    "version": "0.0",
    "href": "https://

...

archie.cochrane.org/rest/reviews

...

<title>Amantadine and rimantadine for influenza A in children and the elderly</title>

<byline>Alves Galvão MG, Rocha Crispino Santos MA, Alves da Cunha AJL</byline>

<group>Acute Respiratory Infections Group</group>

</review>

...

/047199081020060395/translations/fr"
  },
  {
    "language": "hr",
    "title": "Abdominalna dekompresija kod sumnje na ugrožen fetus ili pre-eklampsiju",
    "version": "5.0",
    "href": "https://archie.cochrane.org/rest/reviews

...

/047199081020060395/translations/hr"
  },
  {
    "language": "ta",
    "title": "கருத்தடை சமரசம் / முன்-எக்லம்ப்சியா என சந்தேகிக்கப்படும் அடிவயிற்று சுருக்க சிகிச்சை.",
    "version": "1.0",
    "href": "https://archie.cochrane.org/rest/reviews/047199081020060395/translations/ta"
  }
]

List translations of any published version using Review ID

GET https://archie.cochrane.org/rest/reviews/{Review ID}/{Version}/translations

The response is as described for the previous endpoint.

Get a translation of the latest published version using Review ID

GET https://archie.cochrane.org/rest/reviews/{Review ID}/translations/{language}

Example:

GET https://archie.cochrane.org/rest/reviews/047199081020060395/translations/fr

Returns the translation as either JATS XML or the full JATS package (as determined by the Accept header - see "Encoding of response" above).

Get a translation of the any published version using Review ID

GET https://archie.cochrane.org/rest/reviews/{Review ID}/{Version}/translations/{language}

The response is as described for the previous endpoint.

Getting lists of reviews / searching

The base request for getting a list of reviews is:

GET https://archie.cochrane.org/rest/reviews

This will return all published reviews in Archie, so for most purposes a filter based on query parameters is required.

The response is an XML document listing the key attributes and properties of each review, and a link for accessing the full review, e.g.:

Code Block

language	xml
collapse	true

<reviews count="15">
  <review cdNumber="CD002745" groupId="ARI" reviewId="780800041114324239" searchDate="2011-06-27" stage="R" status="A" checkedOut="false">
    <link href="https://test-

Query parameters

The following query parameters can be used to restrict the search:

groupId (e.g. ARI for Acute Respiratory, see Review Group IDs below): Restrict search to reviews belonging to the specified review group. Default is any group.
stage (R = full Review, P = Protocol, T = Title): Restrict search by review stage. Default is any stage. T is only relevant in combination with published=false.
status (A = Active, W = Withdrawn): Restrict search by status. Default is any status.
phase (A=Authoring, E=Editorial): Restrict search by phase. Default is any phase.
myRole (e.g. myRole=Author): Restrict search to reviews for which the authenticated user has the given role. Default is that roles are not considered.
myPermission (e.g myPermission=write_authoring, see Permission below): Restrict search to reviews for which the authenticated user has the given permission. Default is View permission (view).
startSearchDate (format {yyyy-MM-dd}, e.g. startSearchDate=2014-05-31): Restrict search to reviews with a search date on or after the specified date. Default is any date.
published (true or false). Default is true, which means that only published reviews are returned. If published=false, titles and unpublished protocols are also returned.
issueId (e.g. 2014-1). Limit search to reviews appearing in a specific issue of The Cochrane Library (needs testing).

XPath/XQuery

In addition to query parameters, an XPath or XQuery expression can also be used to restrict the search.

The base URL is:

https://archie.cochrane.org/rest/reviews/xpath/{count expression | exist expression}

The default is exist, which can be left out.

Example 1, reviews that contain a Summary of Findings table:

...

archie.cochrane.org/rest/reviews/

...

Example 2, reviews from the ARI group with more than one Summary of Findings table:

https://archie.cochrane.org/rest/reviews/xpath/count(//SOF_TABLE)>1?groupId=ARI

Example 3, reviews with at least 10 included studies:

https://archie.cochrane.org/rest/reviews/xpath/count(//INCLUDED_STUDIES/STUDY)>=10

Example 4, reviews with at least one forest plot figure (exist is implied):

...

CD002745" rel="self" type="application/xml"/>
    <title>Amantadine and rimantadine for influenza A in children and the elderly</title>
    <byline>Alves Galvão MG, Rocha Crispino Santos MA, Alves da Cunha AJL</byline>
    <group>Acute Respiratory Infections Group</group>
  </review>
  <review cdNumber="CD000243" groupId="ARI" reviewId="482299081614134252" searchDate="2013-03-20" stage="R" status="A"checkedOut="true">
    <link href="https://test-archie.cochrane.org/rest/reviews/

...

CD000243" rel="self" type="application/xml"/>
    <title>Antibiotics for acute maxillary sinusitis in adults</title>
    <byline>Ahovuo-Saloranta A, Rautakorpi U-M, Borisenko OV, Liira H, Williams Jr JW, Mäkelä M</byline>
    <group>Acute Respiratory Infections Group</group>
  </review>
  ...
</reviews>

Query parameters

The following query parameters can be used to restrict the search:

groupId (e.g. ARI for Acute Respiratory, see Review Group IDs below): Restrict search to reviews belonging to the specified review group. Default is any group.
stage (R = full Review, P = Protocol, T = Title): Restrict search by review stage. Default is any stage. T is only relevant in combination with published=false.
status (A = Active, W = Withdrawn): Restrict search by status. Default is any status.
phase (A=Authoring, E=Editorial): Restrict search by phase. Default is any phase.
myRole (e.g. myRole=Author): Restrict search to reviews for which the authenticated user has the given role. Default is that roles are not considered.
myPermission (e.g myPermission=write_authoring, see Permission below): Restrict search to reviews for which the authenticated user has the given permission. Default is View permission (view).
startSearchDate (format {yyyy-MM-dd}, e.g. startSearchDate=2014-05-31): Restrict search to reviews with a search date on or after the specified date. Default is any date.
published (true or false). Default is true, which means that only published reviews are returned. If published=false, titles and unpublished protocols are also returned.
issueId (e.g. 2014-1). Limit search to reviews appearing in a specific issue of The Cochrane Library (needs testing).
translation (language code, e.g. fr). Find reviews where the latest published version has a published translation in the given language. Not compatible with published=false.

Additional endpoints

Get metadata about review

GET https://archie.cochrane.org/rest/reviews/{Review ID}/metadata

Returned MIME type is "application/json".

Get metadata about all versions of a review

GET https://archie.cochrane.org/rest/reviews/{Review ID}/versions

Returned MIME type is "application/json".

Get the document roles associated with a review

GET https://archie.cochrane.org/rest/reviews/{Review ID}/roles

Returned MIME type is "application/json".

Return asset from JATS package

The following return assets referenced from the main JATS XML.

Endpoint	MIME type

...

Note: [ and ] have to be escaped as %5B and %5D.

Example 5, reviews assessed as up-to-date in 2010:

https://archie.cochrane.org/rest/reviews/xpath/COVER_SHEET/DATES/UP_TO_DATE/DATE%5B@YEAR="2010"%5D

Searching within a specific review

https://archie.cochrane.org/rest/reviews/CD000004/xpath//STUDY%5B@YEAR>"1970"%5D

This will return the STUDY elements of the XML only (i.e. not a full review document) where the year is greater than 1970. The returned XML document will include the path of parent elements leading up to the root element (COCHRANE_REVIEW) but any siblings will be excluded, e.g.:

<?xml version="1.0" encoding="iso-8859-1"?>
<COCHRANE_REVIEW DESCRIPTION="For publication" DOI="10.1002/14651858.CD000004.pub2" GROUP_ID="PREG" ID="047199081020060395" MERGED_FROM="" MODIFIED="2012-05-09 15:44:58 +0100" MODIFIED_BY="Sonja Henderson" NOTES="" NOTES_MODIFIED="2012-05-09 15:42:11 +0100" NOTES_MODIFIED_BY="Sonja Henderson" REVIEW_NO="0065" REVMAN_SUB_VERSION="5.1.6" REVMAN_VERSION="5" SPLIT_FROM="" STAGE="R" STATUS="A" TYPE="INTERVENTION" VERSION_NO="8.0">
  <STUDIES_AND_REFERENCES MODIFIED="2008-10-29 16:24:14 +0000" MODIFIED_BY="">
    <STUDIES MODIFIED="2008-10-29 16:13:04 +0000" MODIFIED_BY="">
      <INCLUDED_STUDIES MODIFIED="2008-10-29 16:12:42 +0000" MODIFIED_BY="">
        <STUDY DATA_SOURCE="PUB" ID="STD-MacRae-1971" MODIFIED="2008-10-29 16:12:12 +0000" MODIFIED_BY="" NAME="MacRae 1971" YEAR="1971">
           <REFERENCE MODIFIED="2008-10-29 16:12:12 +0000" MODIFIED_BY="" NOTES="&lt;p&gt;[0711].&lt;/p&gt;" NOTES_MODIFIED="2008-10-29 16:12:12 +0000" NOTES_MODIFIED_BY="" PRIMARY="NO" TYPE="JOURNAL_ARTICLE">
             <AU>MacRae DJ, Mohamedally SM, Willmott MP</AU>
             <TI>Clinical and endocrinological aspects of dysmaturity and the use of intermittent abdominal decompression in pregnancy</TI>
             <SO>Journal of Obstetrics and Gynaecology of the British Commonwealth</SO>
             <YR>1971</YR>
             <VL>78</VL>
             <PG>636-41</PG>
             <IDENTIFIERS/>
          </REFERENCE>
          <IDENTIFIERS/>
        </STUDY>
        <STUDY DATA_SOURCE="PUB" ID="STD-Varma-1973" MODIFIED="2008-10-29 16:12:42 +0000" MODIFIED_BY="" NAME="Varma 1973" YEAR="1973">
          <REFERENCE MODIFIED="2008-10-29 16:12:42 +0000" MODIFIED_BY="" NOTES="&lt;p&gt;[0884].&lt;/p&gt;" NOTES_MODIFIED="2008-10-29 16:12:42 +0000" NOTES_MODIFIED_BY="" PRIMARY="NO" TYPE="JOURNAL_ARTICLE">
            <AU>Varma TR, Curzen P</AU>
            <TI>The effects of abdominal decompression on pregnancy complicated by the small-for-dates fetus</TI>
            <SO>Journal of Obstetrics and Gynaecology of the British Commonwealth</SO>
            <YR>1973</YR>
            <VL>80</VL>
            <PG>1086-94</PG>
            <IDENTIFIERS/>
          </REFERENCE>
          <IDENTIFIERS/>
        </STUDY>
      </INCLUDED_STUDIES>
      <EXCLUDED_STUDIES MODIFIED="2008-10-29 16:13:04 +0000" MODIFIED_BY="">
        <STUDY DATA_SOURCE="PUB" ID="STD-Coppola-1985" MODIFIED="2008-10-29 16:13:04 +0000" MODIFIED_BY="" NAME="Coppola 1985" YEAR="1985">
          <REFERENCE MODIFIED="2008-10-29 16:13:04 +0000" MODIFIED_BY="" PRIMARY="NO" TYPE="OTHER">
            <AU>Coppola F, Battioni M, Vessichelli R, Daoh KS, Bacchi-Modena A</AU>
            <TI>Auxologic results of abdominal decompression in growth disorders of the fetus</TI>
            <SO>Minerva Ginecologica</SO>
            <YR>1985</YR>
            <VL>37</VL>
            <NO>11</NO>
            <PG>645-52</PG>
            <IDENTIFIERS MODIFIED="2008-10-29 16:11:15 +0000" MODIFIED_BY="">
              <IDENTIFIER TYPE="OTHER" VALUE="CN-00279572"/>
            </IDENTIFIERS>
          </REFERENCE>
          <IDENTIFIERS/>
        </STUDY>
      </EXCLUDED_STUDIES>
    </STUDIES>
  </STUDIES_AND_REFERENCES>
</COCHRANE_REVIEW>

Additional endpoints

...


GET https://archie.cochrane.org/rest/reviews/{Review

...

Returned MIME type is "application/json".

Get metadata about all versions of a review

ID}/{Version}/

...

{Asset path}.svg

"image/svg+xml"

GET https://archie.cochrane.org/rest/reviews/{Review

...

ID}/

...

{Version}/{Asset path}.png

"image/png"

Returned MIME type is "application/json".

...

GET https://archie.cochrane.org/rest/reviews/{Review

...

Returned MIME type is "application/json".

Get the workflow and availability status of a review

ID}/{Version}/

...

{Asset path}.jpg

"image/jpeg"

GET https://archie.cochrane.org/rest/reviews/{Review

...

ID}/

...

{Version}/{Asset path}.(xml \| rm5)	"application/xml;charset=utf-8", "application/xml;charset=UTF-8"
GET https://archie.cochrane.org/rest/reviews/{Review ID}/{Version}/{Asset path}.html	"text/html"

Returned MIME type is "application/json".

The field "reviewDBSyncStatus" can have the folllowing values:

NONE: the review is not being synchronized to ReviewDB. This may be because synchronization is disabled globally, or the review type is not supported in ReviewDB.
PUBLISHED_ONLY: all published versions of the review are available in ReviewDB - this value may also be returned if there are no published versions of the review.
PUBLISHED_AND_DRAFTS: synchronization is fully enabled for this review, all published versions and (at least) the most recent draft will be available in ReviewDB.

...

GET https://archie.cochrane.org/rest/reviews/{

...

Review ID}

...

/

...

{

...

Version}/{

...

Asset path}.zip

...

"

...

application/

...

zip"

...

Review Groups IDs

For use with the groupId parameter.

...

Page tree

Page History

Versions Compared

Old Version 2

New Version Current

Key

Contents

Endpoints

Encoding of response

Getting a review

Last published version using CD number

Endpoints

Encoding of response

Getting a review

Last published version using CD number

Last published version using Review ID

Latest version using Review ID

Specific version using Review ID

Checking a review out

Checking a review in

Last published version using Review ID

Latest version using Review ID

Undoing a check-out

Specific version using Review ID

Getting

review translations

List translations of the latest published version using Review ID

List translations of any published version using Review ID

Get a translation of the latest published version using Review ID

Get a translation of the any published version using Review ID

Getting lists of reviews / searching

Query parameters

XPath/XQuery

Query parameters

Additional endpoints

Get metadata about review

Get metadata about all versions of a review

Get the document roles associated with a review

Return asset from JATS package

Searching within a specific review

Additional endpoints

Get metadata about all versions of a review

Get the workflow and availability status of a review

Review Groups IDs