-
Notifications
You must be signed in to change notification settings - Fork 0
API Documentation
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.
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:
-
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:
-
drsPath
description: / delimited string of directory syntax structure (DRS) elements;
required: true;
-
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;
-
id
description: document idenftifier;
required: true; -
version
description: document version;
required: true;
-
name
description: document name;
required: true; -
type
description: document type;
required: true; -
institute
description: institute associated with document;
required: false;
The ES-DOC Publish API is RESTful and supports 3 endpoints:
-
http://api.es-doc.org/1/publish
desciption: document collection endpoint.
supported http verbs: POST
note: new documents are POSTed to this endpoint. -
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. -
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.
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.
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.