Page tree
Skip to end of metadata
Go to start of metadata

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:

http://demo.cytomine.be/restApiDoc/?doc_url=http://demo.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

 

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.

 

URL example

Description

http://demo.cytomine.be/api/user.json

List of users (JSON)

http://demo.cytomine.be/api/user/263676.json

Description of a specific user (JSON)

http://demo.cytomine.be/api/project.json

List of projects (JSON)

http://demo.cytomine.be/api/project/528050.json

Descrpition of a specific project (JSON)

http://demo.cytomine.be/api/project/528050/imageinstance.json

List of images in a specific project (JSON)

http://demo.cytomine.be/api/imageinstance/528460.json

Description of a specific image (JSON)

http://demo.cytomine.be/api/abstractimage/528120/thumb.png?maxSize=1024

Thumbnail of a specific image (PNG)

http://demo.cytomine.be/api/annotation.json?&project=528050

List of annotations in a specific project (JSON)

http://demo.cytomine.be/api/annotation.json?&project=528050&term=528044&users=263676&images=528132

List of annotations of a specific ontology term, in a specific project, for a specific user (human or userjob), in a specific image (JSON)

http://demo.cytomine.be/api/annotation/528401.json

Description of a specific annotation (JSON)

http://demo.cytomine.be/api/userannotation/528401/crop.png

Crop image of a specific annotation (PNG)

http://demo.cytomine.be/api/userannotation/528401/crop.png?increaseArea=2

Crop image of a specific annotation (PNG) with context

http://demo.cytomine.be/api/userannotation/528401/crop.png?zoom=2

Crop image of a specific annotation at zoom level 2 (PNG)

http://demo.cytomine.be/api/userannotation/528401/crop.png?zoom=2&mask=true

Crop binary mask of a specific annotation at zoom level 2 (PNG)

http://demo.cytomine.be/api/userannotation/528401/crop.png?zoom=2&alphaMask=true

Crop alpha mask of a specific annotation at zoom level 2 (PNG)

http://demo.cytomine.be/api/imageinstance/528460/window-23181-14285-1000-1000.png

Tile of size 1000x1000 at a specific location (23181,14285) in a specific image (PNG)

http://demo.cytomine.be/api/imageinstance/528460/window-23181-14285-1000-1000.png?mask=true&review=true&terms=528044

Tile reviewed mask of size 1000x1000 at a specific location (23181,14285) for a specific ontogy term in a specific image (PNG)

http://demo.cytomine.be/api/job/1939560.json

Description of a specific job (JSON) including software parameter values

 

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/

 

  • No labels