# API Client for Java Usage
The API Client for Java is a library that eases the interaction with Cytomine through its HTTP API. The library encapsulates all the technical details so that you can manipulate Cytomine resources as regular Java objects.
If you are not yet familiar with Cytomine HTTP API, have a look at Interact with Cytomine guide.
# Authentication
First at all, you need 3 parameters to connect to a Cytomine instance :
- The Cytomine server URL (example: https://demo.cytomine.be (opens new window))
- Your public key
- Your private key
These keys are personal and must never be shared because they are linked to your Cytomine account. To retrieve these keys, go to the Cytomine graphical interface. In the Cytomine bar, click your-username, then Account in the dropdown. Your keys are at the end of the page.
In the following example, we log in to the Cytomine server (fictive https://mycytomine.com) with a fictive set of keys, and retrieve the information about the current user.
Assuming the cytomine-java-client.jar is in the same folder as the source code, this code can be run with
WARNING
For the sake of this introduction, the set of keys has been hard-coded into the script. Do not hard code your keys into your scripts. As they are personal and has the same value as a password, they should be externalized from your scripts.
# Externalize credentials
A strongly recommended good practice is to externalize your credentials (Cytomine server URL and set of keys) and pass them to your scripts as arguments.
Taking back the last example, we log in again to the Cytomine server and retrieve the information about the current user, but this time, the credentials are not written into the code, but read from the command line instead.
Assuming the cytomine-java-client.jar is in the same folder as the source code, this code can be run with
where you have substituted https//myctomine.com, AAA and ZZZ with your actual credentials.
As a result, your Cytomine username will be printed on the terminal.
# Models
A Cytomine resource (such as a project STUDY-01 or an image cell01.tiff) is an instance of a domain (in the examples: a project, an image).
In the Cytomine API client for Java, a resource is a Java object which is an instance of a model class describing its domain. Each object (thus an instance of a model):
- has a set of attributes corresponding to resource attributes
- is managed itself through
fetch(),save(),update()anddelete()methods that communicate with the Cytomine server - has some utilities to manage HTTP and JSON technical details
Examples of models are Project, ImageInstance, Annotation, Term, User, CurrentUser, etc.
# Fetch a resource
To get data from server, we first need to fetch the resource. Indeed, when you create a new object (such as Project myproject = new Project()), the object (here myproject) is empty. You need to populate this object with data coming from Cytomine.
TIP
The next sections show examples to fetch either a project or an image. The sections are very similar: the API client library is indeed very systematic.
# Example: fetch a project
Supposing the Cytomine server has a project called STUDY-01 with an identifier (ID) 42, the project resource is fetched in Java with:
Behind the scene, the API client library has sent a GET /api/project/42.json request to the Cytomine server and populated myproject with the response content.
Only the project meta information have been retrieved (such as name, ontology identifier, settings, ...). You need to perform other fetch() calls on other models to get the project images, annotations, project members, etc.See the API reference for all details.
# Example: fetch an image
Supposing the Cytomine server has a project with an image called cells01.tiff with an identifier (ID) 13, the image resource is fetched in Java with:
Behind the scene, the API client library has sent a GET /api/imageinstance/13.json request to the Cytomine server and populated myimage with the response content.
Only the image meta information have been retrieved (such as name, width, height, resolution, magnification, ...). You need to perform other fetch() calls on other models to get the annotations, an image thumbnail or window, etc.See the API reference for all details.
# Add a resource
You can create data from your Java code and save them to Cytomine. Starting from an empty instance of model, fill in attributes and then save this new resource to the Cytomine server with the save() method.
We show here an example to create a new project, but the procedure is again very similar for other type of resources.
# Example: save a new project
We will first create an empty Project object and then populate its attributes.
Your new project is now saved to Cytomine ! This new project is also available in the graphical interface in the list of your projects (You might need to refresh the page).
Behind the scene, the API client library has sent a POST /api/project.json request to the Cytomine server with a JSON request body with the new attributes.
See the API reference for the available attributes for each model.
You can use the constructor for some attributes, to reduce code length:
It has exactly the same effect.
# Update a resource
You can update existing Cytomine data from your Java code and make these changes persistent to Cytomine. Starting from a fetched instance of a model, update the attributes you want to change and save these changes to the Cytomine server with the update() method.
We show here an example to update the name of a project, but the procedure is again very similar for other type of resources and attributes.
# Example: update a project
The project has a new name.
Behind the scene, the API client library has sent a PUT /api/project/42.json request to the Cytomine server with a JSON request body with the updated attributes.
See the API reference for the available attributes for each model.
You can also give a map of attribute to update() method:
It has exactly the same effect.
# Delete a resource
It is possible to delete Cytomine resources from the API client library. Deleting resources can have unintended side effects and implies deletion of all dependent resources.
From a fetched resource, call the delete() method.
We show here an example to delete a project (and thus all its images, annotations, etc.), but the procedure is again very similar for other type of resources.
# Example: delete a project
The project and all dependent resources are deleted.
Behind the scene, the API client library has sent a DELETE /api/project/42.json request to the Cytomine server.
You can delete resources without fetching by directly providing ID:
# Fetch embedded resources
Next to the four fetch/add/update/delete actions, some resources provides supplementary actions. These actions are encapsulated in additional model methods.
# Collections
A collection is a list of objects that have the same model. To retrieve all resources from a collection, use the fetch() method on the collection.
Here, we get the list of all projects we have access to:
Behind the scene, the API client library has sent a GET /api/project.json request to the Cytomine server and populated projects with the response content.
To ease collection instantiation, some models have a collection equivalent class. For example, the ProjectCollection is a collection of Project, the ImageInstanceCollection is a collection of ImageInstance, etc.
# Filtering
Sometimes, we are not interested in getting all the projects we have access to, but only a subset of it depending on some filters.
For example, for a project, there are the following filters:
None- the collection of projects can be fetched without any filteruser- to get a collection of projects that a given user is member ofontology- to get a collection of projects that share the given ontologysoftware- to get a collection of projects where the given software is installed.
Supposing the Cytomine server has an ontology with ID 100, the list of project that uses this ontology is retrieved with the fetchWithFilter() method:
Behind the scene, the API client library has sent a GET /api/ontology/100/project.json request to the Cytomine server and populated projects with the response content.
For models that have a Collection class equivalent, there are syntactic sugars to ease collection filtering from some models. In the following example, the list of images in the project myProject is fetched:
# Special case: Annotations
# Search annotations
Annotations are a key features in Cytomine and can be filtered in many ways. You might be interested in getting a listing of all annotations in a subset of images, created by a subset of project members and only associated to a specific term. Such queries are frequent with annotation resources.
AnnotationCollection filtering differs from other collection. With AnnotationCollection, all filters are query modifiers and falls into 2 categories:
- Regular query filters that filter the collection such as
project,user,users,image,images,term, etc. - Query filters that show or hide some annotation attributes, for each annotation in the collection. It can reduce the amount of data transferred between the Cytomine server and your computer, as it can be very large when there are many annotations. Such modifiers start with
show:showTerm,showWKT, etc.
The following example get all annotations:
- in the project with ID 42
- created by project members with ID 7 and 8
- associated to the term 99
and fetch the
termandlocationattributes.
Behind the scene, the API client library has sent a GET /api/annotation.json request to the Cytomine server and populated annotations with the response content.