# Interact with Cytomine

All data available from the Cytomine graphical interface can be manipulated programmatically from your computer. This page introduces the key concepts on how to interact with Cytomine without this graphical interface.

# A RESTful application

Cytomine is a RESTful (opens new window) application. It means that the data stored and managed by Cytomine can be obtained through specific URLs. Contrary to the graphical interface, these URLs only provide relevant information data.

You can test it yourself.

Log to your Cytomine instance with your usual browser. In the example, we assume a fictive https://CYTOMINE_URL Cytomine server.
List the projects you have access to. The URL in your browser is https://CYTOMINE_URL/#/projects. It is the URL to list the projects from the graphical interface.
Now, open a new tab in your browser. Go to https://CYTOMINE_URL/api/project.json. You have a lot of textual information: this is the list of projects you have access to without any graphical information, only data.

This https://CYTOMINE_URL/api/project.json URL is one of these specific URLs which provide only data. It is called an API endpoint.

These API endpoints let Cytomine users, Cytomine apps and external tools interact with Cytomine for various purposes:

Data mining
Scripting
Interact with AI algorithms
Create new graphical interfaces for dedicated purposes
Etc.

The Cytomine HTTP API

The Cytomine HTTP API structures and specifies all the endpoints for the whole application. All the endpoints are secured. It means that you need to be authenticated (with some HTTP mechanisms) so that the Cytomine server accept to treat your request. You keep the rights you have in the graphical interface: if you don't have the rights to perform some actions in the graphical interface, you don't have them by using the API neither. The graphical interface actually relies on the HTTP API.

When dealing with an HTTP API, you have to manage yourself the HTTP layer: create the request, authenticate the user using appropriate HTTP header mechanism, send the request to the server, wait for the response, analyse and parse the received response. In the previous example with your first API test, your browser has managed all of these for you.

When you are running a program outside your browser, you have to manage these yourself, which is not very convenient. To ease interaction with Cytomine, we developed API client libraries for multiple programming languages that do the job for you and let you focus on your task.

Whether you are a data scientist, a machine or deep learning developer or a system administrator, you might be interested to learn how to use these libraries to help you in your tasks.

# API client libraries

To ease interaction with Cytomine, the API client libraries encapsulate all the technical details relative to the HTTP API so that you can manipulate Cytomine resources without complexity. We have API client libraries for 3 languages:

Choose the API client library in the language you prefer. The libraries tend to follow the same structure so that you can switch from a language to another without learning a whole new library. Some libraries embed extra functionalities, such as the API client library for Python which provides helpers for machine and deep learning.

What if my language is missing?

You can interact with Cytomine in other languages that currently do not have a dedicated client library, but you have to manage yourself the usually encapsulated tasks such as HTTP handling, authentication and response parsing.

However, implement an API client library in another language in a good way to contribute to the Cytomine Open Source project.

# Client library structure

We present here the general structure of a Cytomine API client library, but refer to the documentation relative to each library for more details.

The Cytomine API client libraries follows the Object Oriented paradigm (opens new window). A Cytomine resource (such as a project STUDY-01 or an image cell01.tiff) is an instance of a domain (here, the project or the image domain).

In terms of object-oriented programming, a resource is an 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() and delete() methods that communicate with the Cytomine server
has some utilities to manage HTTP and JSON technical details

Examples of models in Cytomine are Project, ImageInstance, Annotation, Term, User, CurrentUser, etc.

A Collection is a representation of a collection of models. It has methods to fetch multiples instances of a model with filters and/or pagination.

# A first script example

Choose the API client library in the language you prefer.
Install the library following the instructions on dedicated pages (in a new development project or environment, depending on the selected language)
When the library is installed, you can use it as any other library into your code.

In this first script, we would like to count the number of annotations that are associated to a given ontology term in all projects we have access to and that have P as first letter in their name.

# What can I do next ?

Learn how to master the API client library for your language with the dedicated guides and examples (for Python, Java or Javascript).

Read the Cytomine apps guide go one step further. It lets you create complete programs manipulating Cytomine data, run them from your computer and save results to Cytomine. Every execution is reported to Cytomine, with the parameters applied to the program. The results of each program execution can then be compared from the graphical interface. Last but not least, these apps can be plugged to Cytomine server and directly launched from the graphical interface on dedicated hardware.

← Introduction Concepts →