Skip to content
Mark A. Greenslade edited this page Feb 2, 2016 · 71 revisions

Overview

The ES-DOC web-service API is designed to support ES-DOC tools and also tools developed by 3rd parties. The API, currently at version 2, 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 web-service API exposes a single HTTP GET endpoint:

      http://api.es-doc.org/2/document/search

Search facets passed as URL query parameters. The following URL query parameters must be supplied for each search:

  1. project
          description: project identifier;
          required: true;
          whitelist: see list of available projects here.
  2. encoding
          description: encoding identifier;
          required: true;
          whitelist: html | json | xml.
  3. timestamp
          description: integer timestamp when client invoked search endpoint;
          required: true;
  4. searchType
          description: type of search being performed;
          required: true;
          whitelist: drs | externalid | id | name
  5. ontology
          description: documentation ontology identifier;
          required: true;
          whitelist: cim.1 | cim.2
  6. language
          description: documentation language code;
          required: true;
          default: en
  7. onJSONPLoad
          description: name of JSONP callback function;
          required: false;

The other URL parameters differ according to search type:

searchType = drs

  1. drsPath
          description: / delimited string of directory syntax structure (DRS) elements;
          required: true;

searchType = externalid

  1. externalID
          description: an external identifier used to resolve one or more documents;
          required: true;
  2. externalType
          description: type of external identifier used to resolve one or more documents;
          required: true;

searchType = id

  1. id
          description: document idenftifier;
          required: true;
  2. version
          description: document version;
          required: true;

searchType = name

  1. name
          description: document name;
          required: true;
  2. type
          description: document type;
          required: true;
  3. 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.

Client Tools

The API can be accessed using the pyesdoc library:

If you have further questions please contact ES-DOC.

Clone this wiki locally