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.
URL example | Description |
---|---|
List of users (JSON) | |
Description of a specific user (JSON) | |
List of projects (JSON) | |
Descrpition of a specific project (JSON) | |
http://research.cytomine.be/api/project/528050/imageinstance.json | List of images in a specific project (JSON) |
Description of a specific image (JSON) | |
http://research.cytomine.be/api/abstractimage/528120/thumb.png?maxSize=1024 | Thumbnail of a specific image (PNG) |
http://research.cytomine.be/api/annotation.json?&project=528050 | List of annotations in a specific project (JSON) |
List of annotations of a specific ontology term, in a specific project, for a specific user (human or userjob), in a specific image (JSON) | |
Description of a specific annotation (JSON) | |
http://research.cytomine.be/api/userannotation/528401/crop.png | Crop image of a specific annotation (PNG) |
http://research.cytomine.be/api/userannotation/528401/crop.png?increaseArea=2 | Crop image of a specific annotation (PNG) with context |
http://research.cytomine.be/api/userannotation/528401/crop.png?zoom=2 | Crop image of a specific annotation at zoom level 2 (PNG) |
http://research.cytomine.be/api/userannotation/528401/crop.png?zoom=2&mask=true | Crop binary mask of a specific annotation at zoom level 2 (PNG) |
http://research.cytomine.be/api/userannotation/528401/crop.png?zoom=2&alphaMask=true | Crop alpha mask of a specific annotation at zoom level 2 (PNG) |
http://research.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) |
Tile reviewed mask of size 1000x1000 at a specific location (23181,14285) for a specific ontogy term in a specific image (PNG) | |
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/