Cytomine API interactive documentation

All the interactions with the Cytomine core are performed through a RESTful API. It makes the link between the server side and a Cytomine client, such a the web interface, the Java or the Python client. All the available services provided by the API are summarized in a user-friendly way on a website automatically installed with Cytomine core. On this interface, you can browser the documentation and directly test API responses in a playground area.

Retrieve the documentation

1) For demo.cytomine.be

For our demo server:

https://research.cytomine.be/restApiDoc/?doc_url=https://research.cytomine.be/restApiDoc/api

For IMS developers, a similar documentation is also available at http://demo-ims.cytomine.be/restApiDoc/?doc_url=http://demo-ims.cytomine.be/restApiDoc/api .

2) For your own instance

The documentation is automatically installed and directly available on your own instance of Cytomine. According to your configuration.sh during the bootstrap procedure, the documentation is available at

• For core: http://__CORE_URL__/restApiDoc/?doc_url=__CORE_URL__
• For IMS: http://__IMS_URL__/restApiDoc/?doc_url=__IMS_URL__ 

Usage

The different services are grouped into several APIs. You can click on a method to obtain its detailed description.

It is also possible to directly test the API response to a request with the playground area on the right. To do so, you have to be connected as a Cytomine user. To obtain a session, you have to connect using the web interface with the same browser.

API endpoint conventions

Basically, an object is created with a POST /api/object.json request.

To get an object, make a GET /api/object/{id}.json request where {id} is the identifier of the requested object. 

To update an object, make a PUT /api/object/{id}.json request where {id} is the identifier of the requested object. 

To delete an object, make a DELETE /api/object/{id}.json request where {id} is the identifier of the requested object. 

To obtain a list of objects, use a GET /api/object.json request.

A list of objects can often be filtered. For example, to obtain the list of projects that are available for a specifier user (which you have rights for), make a GET /api/user/{id}/project.json.

Cytomine API Simple examples

Here are examples of requests and description of typical results.

You have to be logged to the demo instance e.g. using the jsnow/jsnow account.

Please note most of these requests are already implemented in Python and Java functions in our clients so you don't have to reimplement communication mechanisms.

Grails plugin

To document our Rest API, we have built a Grails plugin (public), Rest Api Doc, that can be reused to document other REST API.

Rest Api Doc source: https://github.com/loic911/restapidoc

Rest Api Doc Documentation: http://loic911.github.io/restapidoc/