Export API

Table of Contents

Overview

• Overview

Exports

• Get an export of a source version
• Create an export of a source version
• Determine the status of an export file
• Delete an export file

Other

• Useful HTTPie commands

Overview

The API provides an export endpoint for source versions (and in the future for collection versions) that provides access to create, get, and delete cached exports of specific versions of sources. Requesting an export returns a status of 200 OK with the exportURL in the response header if the file already exists, or a 204 No Content if the export is still being processed. The export filename includes the lastUpdated timestamp of the export, which can be used to fetch the diff between an export and the current state of the source.

Exports are a compressed tar of the JSON results. The export filename takes the following form:

[:sourceName]_[:sourceVersion].[:lastUpdated].tar

The JSON results are the equivalent of the following REST API request:

GET /orgs/[:org]/sources/[:source]/[:sourceVersion]/?includeConcepts=true&includeMappings=true&includeRetired=true&limit=0

To fetch the diff between a lastUpdated timestamp and the current state of a source:

GET /orgs/[:org]/sources/[:source]/?includeConcepts=true&includeMappings=true&includeRetired=true&limit=0&updatedSince=[:lastUpdated]

Refer to sources documentation for details on the above request.

The Subscriptions documentation describes how the export functionality can be used to subscribe to a source to keep a client system in synch.

Future Considerations

• Add lastUpdated into the response header of GET request (not just the filename)

Get an export of a source version

• Get the export URL for the specified source version. This has three possible results:
  • If the export exists, returns a status code of 200 OK and sets the exportURL attribute in the response headser to the fully specified URL to download the export file
  • If the export file does not exist or is still being processed, returns a status code of 204 No Content and exportURL is empty; note that this triggers the export file to be created if it is not already being processed
  • If the export request is invalid or not authorized, returns the error code

GET /orgs/[:org]/sources/[:source]/[:sourceVersion]/export/
GET /users/[:user]/sources/[:source]/[:sourceVersion]/export/
GET /user/sources/[:source]/[:sourceVersion]/export/

• Notes
  • The sourceVersion is required
  • The API returns the fully specified URL of the export file in the exportURL attribute of the response header

Example

• Fetch the export URL for v2.2 of the CIEL source

GET /orgs/CIEL/sources/CIEL/v2.2/export/

Response

• If the export file is cached:

Status: 200 OK
Response Header:
exportURL: https://ocl-source-export-production.s3.amazonaws.com/CIEL/CIEL_55572f688a86f24b48d935be.20150516122820.tgz?Signature=fmBSI6hL9IhN4mu4W5x%2FPFs5uxw%3D&Expires=1431864368&AWSAccessKeyId=...

• If the export file is still being prepared or does not exist; this triggers the export to be created

Status: 204 No Content
Response Header:
exportURL: 

• If the requested export is invalid - returns the appropriate error code

Create an export of a source version

• Create an export file for the specified source version; if it already exists, this triggers the existing file to be deleted and recreated

POST /orgs/[:org]/sources/[:source]/[:sourceVersion]/export/
POST /users/[:user]/sources/[:source]/[:sourceVersion]/export/
POST /user/sources/[:source]/[:sourceVersion]/export/

• Notes
  • The sourceVersion is required
  • This request only triggers the creation of the export file and does not return the exportURL. It is necessary to follow up with a GET request after the file has been processed in order to get the exportURL

Example

• Create (or re-create) the export URL for v2.2 of the CIEL source

POST /orgs/CIEL/sources/CIEL/v2.2/export/

Response

Status: 204 No Content

Determine the status of an export file

• Returns the current status of an export file. Output is identical to the GET request.

HEAD /orgs/[:org]/sources/[:source]/[:sourceVersion]/export/
HEAD /users/[:user]/sources/[:source]/[:sourceVersion]/export/
HEAD /user/sources/[:source]/[:sourceVersion]/export/

Delete an export file

• Deletes a specific export file

DELETE /orgs/[:org]/sources/[:source]/[:sourceVersion]/export/
DELETE /users/[:user]/sources/[:source]/[:sourceVersion]/export/
DELETE /user/sources/[:source]/[:sourceVersion]/export/

• Notes
  • The passed authorization token must have administrative access to the source in order to delete the export file

Useful HTTPie commands

• You can use httpie (installed on the server) to start/check export:

http HEAD $OCL_API_HOST/orgs/CIEL/sources/CIEL/55497986525c3173c33d2c4a/export/ Authorization:"Token $OCL_API_TOKEN" --print HBhb
http GET $OCL_API_HOST/orgs/CIEL/sources/CIEL/55497986525c3173c33d2c4a/export/ Authorization:"Token $OCL_API_TOKEN" --print HBhb