Page tree
Skip to end of metadata
Go to start of metadata

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

The Review Database API provides more granular access to review content and data.

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 headerDescription
application/xml;charset=iso-8859-1Review in rm5 format, iso-8859-1 charset
application/xml;charset=utf-8Review in rm5 format, utf-8 charset
application/x-jats+xml;charset=utf-8Review in JATS format, utf-8 charset
application/x-dar+zipDownload 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 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

Getting review translations

List translations of the latest published version using Review ID

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

Example:

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

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

[
  {
    "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/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"
  }
]

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

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

<reviews count="15">
  <review cdNumber="CD002745" groupId="ARI" reviewId="780800041114324239" searchDate="2011-06-27" stage="R" status="A" checkedOut="false">
    <link href="https://test-archie.cochrane.org/rest/reviews/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".

Generate a forest plot

GET https://archie.cochrane.org/rest/reviews/{CD Number}/graphics/forestplot/{Comparison ID}/{Outcome ID}

Returned MIME type is "image/png".

Return asset from JATS package

The following return assets referenced from the main JATS XML.

EndpointMIME type
GET https://archie.cochrane.org/rest/reviews/{Review ID}/{Version}/{Asset path}.svg"image/svg+xml"
GET https://archie.cochrane.org/rest/reviews/{Review ID}/{Version}/{Asset path}.png"image/png"
GET https://archie.cochrane.org/rest/reviews/{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"

Review Groups IDs

For use with the groupId parameter.

Group NameID
Acute Respiratory Infections GroupARI
Airways GroupAIRWAYS
Anaesthesia GroupANAESTH
Back GroupBACK
Bone, Joint and Muscle Trauma GroupMUSKINJ
Breast Cancer GroupBREASTCA
Childhood Cancer GroupCHILDCA
Colorectal Cancer GroupCOLOCA
Consumers and Communication GroupCOMMUN
Cystic Fibrosis and Genetic Disorders GroupCF
Dementia and Cognitive Improvement GroupDEMENTIA
Depression, Anxiety and Neurosis GroupDEPRESSN
Developmental, Psychosocial and Learning Problems GroupBEHAV
Drugs and Alcohol GroupADDICTN
Ear, Nose and Throat Disorders GroupENT
Effective Practice and Organisation of Care GroupEPOC
Epilepsy GroupEPILEPSY
Eyes and Vision GroupEYES
Fertility Regulation GroupFERTILREG
Gynaecological Cancer GroupGYNAECA
Haematological Malignancies GroupHAEMATOL
Heart GroupVASC
Hepato-Biliary GroupLIVER
HIV/AIDS GroupHIV
Hypertension GroupHTN
Incontinence GroupINCONT
Infectious Diseases GroupINFECTN
Inflammatory Bowel Disease and Functional Bowel Disorders GroupIBD
Injuries GroupINJ
Lung Cancer GroupLUNGCA
Menstrual Disorders and Subfertility GroupMENSTR
Metabolic and Endocrine Disorders GroupENDOC
Methodology Review GroupMETHOD
Movement Disorders GroupMOVEMENT
Multiple Sclerosis and Rare Diseases of the Central Nervous System GroupMS
Musculoskeletal GroupMUSKEL
Neonatal GroupNEONATAL
Neuromuscular Disease GroupNEUROMUSC
Occupational Safety and Health GroupOCCHEALTH
Oral Health GroupORAL
Pain, Palliative and Supportive Care GroupSYMPT
Peripheral Vascular Diseases GroupPVD
Pregnancy and Childbirth GroupPREG
Prostatic Diseases and Urologic Cancers GroupPROSTATE
Public Health GroupPUBHLTH
Renal GroupRENAL
Schizophrenia GroupSCHIZ
Sexually Transmitted Infections GroupSTI
Skin GroupSKIN
Stroke GroupSTROKE
Tobacco Addiction GroupTOBACCO
Upper Gastrointestinal and Pancreatic Diseases GroupUPPERGI
Wounds GroupWOUNDS

Permissions

For use with the myPermission parameter.

Permission NameParameter Value

Delete Document
View
Read Published Versions
Read Versions to be Published
Read Author Draft Versions
Read Editorial Draft Versions
Read Shared Draft Versions
Write During Authoring Phase
Write During Editorial Phase
Revert
View Author Roles
Edit Author Roles
View Editor Roles
Edit Editor Roles
Publish
Select Review Topics
Edit Properties

delete
view
read_published
read_to_be_published
read_author_drafts
read_editorial_drafts
read_shared_drafts
write_authoring
write_editorial
revert
view_author_roles
edit_author_roles
view_editor_roles
edit_editor_roles
publish
select_topics
edit_properties