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

Subscription

• Subscription process

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 and collections. A lastUpdated date is included in the response header of exports, which can be used to fetch the diff between an export and the current state of the source or collection. Exports are compressed json that are cached.

Get an export of a source version

• Gets the export file for the specified source version; if it does not exist, this triggers the export file to be created and returns the appropriate status 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 and should be a "released" source version
  • The API returns the fully specified URL of the export file in the exportURL attribute of the response header

Example

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

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

Response (not completed)

• If the export file is cached:

Status: 200 OK
Response Header:
exportURL: 

• If the export file is still being prepared
• If the export file does not exist
• If the requested export is invalid

Create an export of a source version

• Creates 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/

Determine the status of an export file

• Returns the current status of an export file. Possible values are that is exists/cached, is being processed, does not exist, or is invalid

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/

Subscription process

For the first synchronization, fetch the most recent export of a released source version

• Determine the latest released version of the source:

GET /orgs/CIEL/sources/CIEL/versions/?limit=1&released=true

• Retrieve the full export of the latest released source version (returns a compressed tar file of the json) and record the lastUpdated timestamp included in the response header -- NOTE that if the export file does not already exist, is still being processed, or is invalid, the API returns a specific status code or an error message (will document these shortly)

GET /orgs/CIEL/sources/CIEL/[:sourceVersion]/export/

• Fetch all updates to the source that are more recent than the export using the lastUpdated timestamp

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

For subsequent synchronizations, fetch records that have been updated since the lastUpdated timestamp

• Fetch all updates to the source that are more recent than lastUpdated from the previous synchronization

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

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

OLD DOCUMENTATION

• To grab the diff between a newer version of the source (rather than the latest):

GET /orgs/CIEL/sources/CIEL/v2.3/?includeMappings=true&includeConcepts=true&includeRetired=true&limit=0&updatedSince=[lastUpdated]

Requesting a full source version export

Results from Discussion

• Maximum limit=500 for all GET requests - error if limit is set to an amount above that
• Paging needs to be supported for GET source details with includeMappings and includeConcepts set to true
• Source versions
  • Add support for "released" URL parameter to source versions GET request (e.g. GET /orgs/CIEL/sources/CIEL/versions/?released=true)
  • Add default sort of created_on descending for source versions
  • Goal is that a subscription client could get the most recent published source version using the following: GET /orgs/CIEL/sources/CIEL/versions/?limit=1&released=true

Source subscription process

• Get the latest version info for a source

GET /orgs/CIEL/sources/CIEL/versions/?limit=1&released=true

• Get the full export of the latest version. The response header will include a lastUpdated field that should be captured.

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

• Fetch all updates to the source that are more recent than lastUpdated:

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

• To grab the diff between a newer version of the source (rather than the latest):

GET /orgs/CIEL/sources/CIEL/v2.3/?includeMappings=true&includeConcepts=true&includeRetired=true&limit=0&updatedSince=[lastUpdated]

Working with full, cached exports

• Request header:
  • Authorization: Token ...
  • Format/filetype - 'application/zip'
• Response header:
  • all the normal stuff, plus...
  • format/filetype - 'application/zip'
  • "lastUpdated" of the content (e.g. concepts/mappings) inside the export - this is required so that the user can request a diff to get to the latest version
  • datetime info of when the file was created
• Response - same as the current export
• Filename - suggested naming: relative url of the source version plus the datetime of the last updated content