Server API

Overview

CVAT server provides HTTP REST API for interaction. Each client application - be ita command line tool, browser or a script - all interact with CVAT via HTTP requests andresponses:

CVAT server interaction image

API schema

You can obtain schema for your server at<yourserver>/api/docs. For example,the official CVAT.ai application has API documentationhere.

Examples

Here you can see how a task is created in CVAT:

Task creation example

  1. At first, we have to login
  2. Then we create a task from its configuration
  3. Then we send task data (images, videos etc.)
  4. We wait for data processing and finish

Design principles

Common pattern for our REST API is<VERB> [namespace] <objects> <id> <action>.

  • VERB can bePOST,GET,PATCH,PUT,DELETE.
  • namespace should scope some specific functionality likeauth,lambda.It is optional in the scheme.
  • Typicalobjects aretasks,projects,jobs.
  • When you want to extract a specific object from a collection, just specify itsid.
  • Anaction can be used to simplify REST API or provide an endpoint for entitieswithoutobjects endpoint likeannotations,data,data/meta. Note: actionshould not duplicate other endpoints without a reason.

When you’re developing new endpoints, follow these guidelines:

  • Use nouns instead of verbs in endpoint paths. For example,POST /api/tasks instead ofPOST /api/tasks/create.
  • Accept and respond with JSON whenever it is possible
  • Name collections with plural nouns (e.g./tasks,/projects)
  • Try to keep the API structure flat. Prefer two separate endpointsfor/projects and/tasks instead of/projects/:id1/tasks/:id2. Usefilters to extract necessary information like/tasks/:id2?project=:id1.In some cases it is useful to get alltasks. If the structure ishierarchical, it cannot be done easily. Also you have to know both:id1and:id2 to get information about the task.Note: for now we acceptGET /tasks/:id2/jobs but it should be replacedby/jobs?task=:id2 in the future.
  • Handle errors gracefully and return standard error codes (e.g.201,400)
  • Allow filtering, sorting, and pagination
  • Maintain good security practices
  • Cache data to improve performance
  • Versioning our APIs. It should be done when you delete an endpoint or modifyits behaviors. Versioning uses a schema withAccept header with vendor media type.

Links