Skip to content

Guides | Rest API

Jump to bottom
Hongsoog Kim edited this page Oct 12, 2022 · 34 revisions

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 ProjectManager {
    +status_report()
    }

    class MemberContainer {
    +start()
    +stop()
    +status_request()
    }
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 these 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

Core 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;

classDiagram

    class ProjectManager {
    +status_report()
    }
Loading 
### status_report()

**HTT GET Message calling from Member Containers.**
```HTML
http://<DOCKER_HOST_IP>:<PROJECT_MANAGER_PORT>/?status_report&
  container_id=<container_id>&
  user_id=<user_id>&
  project_id=<project_id>&
  status=<status>

Equivalent route function form in Python Web Framework (e.g, Django)

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)

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
  • 'bms' : Base Model Select Container
  • 'vis2code' : Model Visualizer 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

Core 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;

classDiagram
    class MemberContainer {
    +start()
    +stop()
    +status_request()
    }
Loading

start()

The Project Manager will call start() exposed by member container in order to make the member container start its task associated with <project_id> and <user_id>.

HTT GET Message calling from Member Containers.

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

Equivalent route function form in Python Web Framework (e.g, Django)

start(project_id=<project_id>, user_id=<user_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
  • <user_id>, project_id indicate the associated project user's ID and project ID respectively for the 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()

The Project Manager will call stop() exposed by member container in order to enforce the member container stop its current task associated with <project_id> and <user_id>.

HTT GET Message calling from Member Containers.

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

Equivalent route function form in Python Web Framework (e.g, Django)

stop(project_id=<project_id>, user_id=<user_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
  • <user_id>, project_id indicate the associated project user's ID and project ID respectively for the 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()

The Project Manager calls status_request() with following use cases;

  • periodically (defined by its internal frequency) calls status_request(project_id=<project_id>, user_id=<user_id>) exposed by member container in order to check the task status in the member container after call to `start(), or
  • instantly calls status_request(project_id="", user_id="") exposed by member container in order to check the container readiness check while project configuration phase before any calll to start().

HTT GET Message calling from Member Containers.

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

Equivalent route function form in Python Web Framework (e.g, Django)

status_request(project_id=<project_id>, user_id=<user_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. user_id, project_id can be set as empty string (""), if lstatus_request() used for just member container ready status check.

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
    • "ready" : container service ready, when called with status_request(project_id="", user_id="").
    • "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's States

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

Extra Rest APIs provided by the Member Containers

Project Manager

TBD

Labelling

TBD

Base Model Select

TBD

Backbone NAS

TBD

Neck NAS

TBD

Cloud Deployment

TBD

OnDevice Deployment

TBD

👉Note

  • This page might contain some wide rendered images. If you want to see the whole contents with wider page, please use Wide GitHub extension of Chrome.
  • If you are experiencing the error on rendered images due to the low-bandwith Internet delay, please use F5 function key for refreshing current page.
Clone this wiki locally