Guides | Rest API

Rest API Guides

In TANGO, there are two types of container.

• Main container : Project Manager, which makes the other containers start and stop, as well as coordinates them to proceed workflow.
• Member container: All containers except for Project Manager, which perform specific task in whole workflow.

Project Manager keeps the project details and coordinates the member container's tasks with start() to start the specific task of the member container, periodically (defined as heart beat frequency, default: 2 sec) calls status_request() of the member container to get the member container status. Member container sends the Project Manager a status message with `status_report() that shows if its task was finished successfully or not

classDiagram
    direction LR

    Project Manager "1" .. "n" Member Container

    class Project Manager
    Project Manager: +status_report(container_id=<container_id>, user_id=<user_id>, project_id=<project_id>, status=<status>)

    class Member Container
    Member Container: +start(project_id=<project_id>, user_id=<user_id>)
    Member Container: +stop(project_id=<project_id>, user_id=<user_id>)
    Member Container: +status_request(project_id=<project_id>, user_id=<user_id>)

Loading

Containers should implement the following core Rest APIs for other containers calls;

Container Type	Rest API exposed to other containers
Main Container	status_report()
Member Container	start(), stop(), status_request()

• In addition to this core APIs, each container can implement its own private or public APIs if needed.
• Refer to Guide | TANGO Architecture for usage of the Rest APIs between Project Manager and Member Containers

Rest APIs provided by the Project Manager

As a whole workflow coordinator, the Project Manager should expose following API for member containers that report their task status using following status_report() function when their tasks was finished;

status_report(container_id=<container_id>, user_id=<user_id>, project_id=<project_id>, status=<status>)

Equivalent route when it used for HTTP GET/POST when used from Member Containers.

http://<DOCKER_HOST_IP>:<PROJECT_MANAGER_PORT>/?status_report&
  container_id=<container_id>&
  user_id=<user_id>&
  project_id=<project_id>&
  status=<status>

• <DCOKER_HOST_IP>: the IP address or DNS Name of the machine that runs Docker Engine
• <PROJECT_MANAGER_PORT> is port number associated with the Project Manager(e.g, 8085)
  • refer to Continer Port Map Guide

The Project Manager Container should respond with the HTTP response message

• 200 OK, when it receive the status report normally.

Arguments use in this API

container_id indicates the container id who reports the status. possible values for <container_id> are as follows:

• 'labelling' : Dataset Labeling Tool Container
• 'visualization' : Model Visualizer Container
• 'bms' : Base Model Select Container
• 'backbone_nas' : Backbone NAS Container
• 'neck_nas' : Neck NAS Container
• 'code_gen' : Code Generation Container
• 'cloud_deploy' : Deployment Container for Cloud target
• 'ondevice_deploy' : Deployment Container for OnDevice target

user_id, project_id indicate the project user's ID and project ID respectively, which were delivered parameters via start() from Project Manager to Member container.

status indicates whether the task in the member container is success or failed possible values for <status> are as follows:

• 'success' : successful completion of the task in the member container
• 'failed' : failure of the task in the member container

---

Rest APIs provided by the member containers

All member containers should expose following core APIs for Project Manager to start/stop the member container's task and query on the task status;

start(project_id=<project_id>, user_id=<user_id>)

Equivalent route when it used for HTTP GET/POST from Project Manager;

http://<DOCKER_HOST_IP>:<MEMBER_CONTAINER_PORT>/?start&
  user_id=<user_id>&
  project_id=<project_id>&

• <DCOKER_HOST_IP>: the IP address or DNS Name of the machine that runs Docker Engine
• <MEMBER_CONTAINER_PORT>: port number associated with the correspoding Member Container
  • refer to Continer Port Map Guide

user_id, project_id indicate the project user's ID and project ID respectively.

The Project Manager calls start() exposed by member container in order to make the member container start its task.

The Member Container should respond with the HTTP response message

• 200 OK with 'Content-Type' / 'text/plain'="starting", when it start it's task successfully.
• 200 OK with 'Content-Type' / 'text/plain'="error" , when it did not start it's task.

stop(project_id=<project_id>, user_id=<user_id>)

Equivalent route when it used for HTTP GET/POST from Project Manager;

http://<DOCKER_HOST_IP>:<MEMBER_CONTAINER_PORT>/?stop&
  user_id=<user_id>&
  project_id=<project_id>&

• <DCOKER_HOST_IP>: the IP address or DNS Name of the machine that runs Docker Engine
• <MEMBER_CONTAINER_PORT>: port number associated with the correspoding Member Container
  • refer to Continer Port Map Guide

user_id, project_id indicate the project user's ID and project ID respectively.

The Project Manager calls stop() exposed by member container in order to enforcely make the member container stop its task.

The Member Container should respond with the HTTP response message

• 200 OK with 'Content-Type' / 'text/plain'="finished", when it stops it's task successfully.
• 200 OK with 'Content-Type' / 'text/plain'="error" , when it did not stop it's task.

status_request(project_id=<project_id>, user_id=<user_id>)

Equivalent route when it used for HTTP GET/POST from Project Manager;

http://<DOCKER_HOST_IP>:<MEMBER_CONTAINER_PORT>/?status_request&
  user_id=<user_id>&
  project_id=<project_id>&

• <DCOKER_HOST_IP>: the IP address or DNS Name of the machine that runs Docker Engine
• <MEMBER_CONTAINER_PORT>: port number associated with the correspoding Member Container
  • refer to Continer Port Map Guide

user_id, project_id indicate the project user's ID and project ID respectively.

The Project Manager periodically (defined by its internal frequency) calls status_request() exposed by member container in order to check the task status in the member container.

The Member Container should respond with the HTTP response with body one of the followings;

• 200 OK with 'Content-Type' / 'text/plain'="<status_code>", where <status_code> is one of the following values
  • "started" : already started its task.
  • "running" : currently running its task
  • "stopped" : stopped it task for response to stop() call or any internal reason.
  • "failed": fails to complete its task.
  • "completed": finishes its task successfully.

Member container state

stateDiagram-v2
  [*] --> Started : start()
  Started --> Running
  Started --> Failed: Internal Error
  Started --> Stopped: stop()
  Running --> Stopped: stop()
  Running --> Failed: Internal Error
  Running --> Completed
  Failed --> [*]
  Stopped --> [*]
  Completed --> [*]

Loading