Skip to content

Guides | Rest API

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

Rest API Guides

ToC

In TANGO, there are two types of container.

  • Leader Container : For example, Project Manager, which makes the other containers start and stop, as well as coordinates them to proceed TANGO workflow.
  • Member Container: All containers except for Project Manager, which perform specific task in whole workflow under control of Leader Container.

Leader Container (i.e, Project Manager) keeps the project details and coordinates the Member Containers' tasks

  • with call to start() to start the specific task of the member container, periodically (defined as heart beat frequency, default: 2 sec),
  • with call to stop() to stop the current undergoing task of the member container, and/or
  • with call to status_request() of the member container to get the member container status, and

Member Container spontaneously report its task successful completion of failure

  • with call status_report(), which is provided and exposed by Project Manager, to notify that it has finished its task 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 service;

Container Type Rest API exposed to other containers
Leader 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 among Leader Container and Member Containers.

Note on API provider and consumer
Don't confuse between API provider and API consumer. For example,

  • the main consumers of status_report(), provided by the Leader Container (i.e., Project Manager), are Member Containers.
  • Vice versa, the main consumer of start(), stop(), and status_request, provided by Member Containers, is the Leader Container (i.e., Project Manager)

Core Rest APIs provided by the Project Manager

As a whole workflow coordinator, the Leader Container (Project Manager) should expose the following APIs 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()

**HTTP 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>)
  • <DOCKER_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)

Arguments:

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 Leader Container (Project Manager) to the Member Containers. 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

Returns:

The Leader Container (Project Manager) should respond with the following HTTP response message;

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

Core Rest APIs provided by the Member Containers

All Member Containers should expose following core APIs for Leader Container (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 Leader Container (Project Manager) will call start(), provided and exposed by Member Container, to make the Member Container start its task associated with <project_id> and <user_id>.

HTTP 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 corresponding 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 Leader Container (Project Manager) will call stop(), provided and exposed by Member Container, in order to enforce the Member Container stop its current task associated with <project_id> and <user_id>.

HTTP 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 corresponding 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 Leader Container (Project Manager) wil calls status_request(), provided and exposed by Member Container under following two conditions;

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

HTTP 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 corresponding 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 status_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