API Documentation

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:

      Search - supports the resolution of various identifiers to project specific documentation;
      Publish - supports remote documentation creation, retrieval, update and deletion.
      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

Facets are passed as URL query parameters. The following URL query parameters must be supplied for each search:

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

The other URL parameters differ according to search type:

searchType = drs

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

searchType = externalid

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

searchType = id

id
      description: document idenftifier;
      required: true;
version
      description: document version;
      required: true;

searchType = name

name
      description: document name;
      required: true;
type
      description: document type;
      required: true;
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/2/document/retrieve?document_id={X}&document_version={Y}&encoding={Z}
         description: document retrieval endpoint.
         supported http verbs: GET

2. http://api.es-doc.org/2/document/create](http://api.es-doc.org//2/document/create
         description: create new document
         supported http verbs: POST
         note: set HTTP header Content-Type=application/json

3. http://api.es-doc.org/1/publish/{id}/{version}
         description: 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:

• installation: pip install pyesdoc
• source code: https://github.com/ES-DOC/esdoc-py-client

If you have further questions please contact ES-DOC.