API Documentation

Overview

The ES-DOC API has been designed not only to support the set of tools developed and maintained by the ES-DOC team but also, overtime, to support tools developed by 3rd parties. The API, currently at version 1, is a set of relatively simple web-service end-points that can be invoked from both a browser and scripts.

The ES-DOC API supports 3 types of operation:

1. Search - supports the resolution of various identifiers to project specific documentation;
2. Publish - supports remote documentation creation, retrieval, update and deletion.
3. Compare - supports download of documentation metadata appropriate for delivering comparison use cases.

Search

The ES-DOC Search API exposes a single faceted endpoint: http://api.es-doc.org/1/search. This endpoint supports the HTTP GET verb and the JSONP protocol. Search facets are passed as URL query parameters.

The following URL query parameters are standard and must be supplied for each search:

1. project
         description: project identifier;
         required: true;
         whitelist: cmip5 | dcmip-2012 | qed-2013 | cordex.
2. timestamp
         description: timestamp when client invoked search endpoint;
         required: true;
3. searchType : type of search being performed, must be one of:
         description: type of search being performed;
         required: true;
         whitelist: documentByDRS | documentByExternalID | documentByID | documentByName | documentSummaryByName | se1

The other URL parameters differ according to search type:

documentByDRS

1. language
         description: document language identifier;
         required: true;
         whitelist: see ISO 639-1 codes
2. encoding
         description: document encoding type;
         required: true;
         whitelist: json | xml | xml-metafor-cim-v1;
3. ontology
         description: document ontology;
         required: true;
         whitelist: cim.1;
4. drsPath
         description: / delimited string of directory syntax structure (DRS) elements;
         required: true;

documentByExternalID

1. language
         description: document language identifier;
         required: true;
         whitelist: see ISO 639-1 codes
2. encoding
         description: document encoding type;
         required: true;
         whitelist: json | xml | xml-metafor-cim-v1;
3. ontology
         description: document ontology;
         required: true;
         whitelist: cim.1;
4. externalID
         description: an external identifier used to resolve one or more documents;
         required: true;
5. externalType
         description: type of external identifier used to resolve one or more documents;
         required: true;
6. typeWhiteList
         description: list of document types to include in search result;
         required: false;
7. typeBlackList
         description: list of document types to exclude in search result;
         required: false;

documentByID

1. language
         description: document language identifier;
         required: true;
         whitelist: see ISO 639-1 codes
2. encoding
         description: document encoding type;
         required: true;
         whitelist: json | xml | xml-metafor-cim-v1;
3. ontology
         description: document ontology;
         required: true;
         whitelist: cim.1;
4. id
         description: document idenftifier;
         required: true;
5. version
         description: document version;
         required: true;

documentByName

1. language
         description: document language identifier;
         required: true;
         whitelist: see ISO 639-1 codes
2. encoding
         description: document encoding type;
         required: true;
         whitelist: json | xml | xml-metafor-cim-v1;
3. ontology
         description: document ontology;
         required: true;
         whitelist: cim.1;
4. name
         description: document name;
         required: true;
5. type
         description: document type;
         required: true;
6. institute
         description: institute associated with document;
         required: false;

se1

1. documentLanguage
         description: document language identifier;
         required: true;
         whitelist: see ISO 639-1 codes
2. documentType
         description: document type identifier;
         required: true;
3. documentVersion
         description: document type identifier;
         required: true;
         whitelist: all | latest | a positive integer;
4. institute
         description: institute associated with document;
         required: false;

Publish

The ES-DOC Publish API is RESTful and supports 3 endpoints:

1. http://api.es-doc.org/1/publish
         desciption: document collection endpoint.
         supported http verbs: POST
         note: new documents are POSTed to this endpoint.

2. http://api.es-doc.org/1/publish/{id}
         desciption: document instance endpoint.
         supported http verbs: GET, DELETE, HEAD
         note: existing document is retrieved, deleted via this endpoint.

3. http://api.es-doc.org/1/publish/{id}/{version}
         desciption: document version endpoint.
         supported http verbs: GET, DELETE, HEAD
         note: existing document version is retrieved, deleted via this endpoint.

NOTE - the publishing endpoint is currently available in test mode only until relevant security policies are agreed upon by ES-DOC partners.

Compare

The ES-DOC Compare API does not expose an endpoint It makes available data in json/jsonp formats so that 3rd parties can build alternative comparators. The setup data is available here. The setup data files are named according to the following convention: compare.setup.{project-code}.{comparator-type}.{json | jsonp}.

Client Tools

The API can be accessed via the following client tools:

1. pyesdoc: A python client that exposes publishing functions. Source code can be found here.

If you have further questions please contact ES-DOC.