restful_microservice_interfaces.md

Microservice Endpoints

The REST API has a default maximum body size of 10KB, this can be changed by setting the environment variable MAX_BODY_SIZE in bytes.

Path	Description
GET /models	Return supported models.
GET /pipelines	Return supported pipelines.
GET /pipelines/status	Return status of all pipeline instances.
GET /pipelines/{name}/{version}	Return pipeline description.
POST /pipelines/{name}/{version}	Start new pipeline instance.
GET /pipelines/{instance_id}	Return pipeline instance summary.
GET /pipelines/{name}/{version}/{instance_id}	Return pipeline instance summary.
GET /pipelines/status/{instance_id}	Return pipeline instance status.
GET /pipelines/{name}/{version}/{instance_id}/status	Return pipeline instance status.
DELETE /pipelines/{instance_id}	Stops a running pipeline or cancels a queued pipeline.
DELETE /pipelines/{name}/{version}/{instance_id}	Stops a running pipeline or cancels a queued pipeline.

The following endpoints are deprecated and will be removed in a future release.

Path	Description
GET /pipelines/{name}/{version}/{instance_id}	Return pipeline instance summary.
GET /pipelines/{name}/{version}/{instance_id}/status	Return pipeline instance status.
DELETE /pipelines/{name}/{version}/{instance_id}	Stops a running pipeline or cancels a queued pipeline.

GET /models

Return supported models

Responses

200 - Success

application/json

Example

[
  {
    "name": "name",
    "description": "description",
    "type": "IntelDLDT",
    "version": 0
  }
]

GET /pipelines

Return supported pipelines

Responses

200 - Success

application/json

Example (generated)

[
  {
    "description": "description",
    "type": "GStreamer",
    "parameters": {
      "key": {
        "default": ""
      }
    }
  }
]

GET /pipelines/status

Return status of all pipeline instances.

Responses

200 - Success

application/json

Example (generated)

[
 {
   "id": 1,
   "state": "COMPLETED",
   "avg_fps": 8.932587737800183,
   "start_time": 1638179813.2005367,
   "elapsed_time": 72.43142008781433,
   "message": "",
   "avg_pipeline_latency": 0.4533823041311556
 },
 {
   "id": 2,
   "state": "RUNNING",
   "avg_fps": 6.366260838099841,
   "start_time": 1638179886.3203313,
   "elapsed_time": 16.493194580078125,
   "message": "",
   "avg_pipeline_latency": 0.6517487730298723
 },
 {
   "id": 3,
   "state": "ERROR",
   "avg_fps": 0,
   "start_time": null,
   "elapsed_time": null,
   "message": "Not Found (404), URL: https://github.com/intel-iot-devkit/sample.mp4, Redirect to: (NULL)"
 }
]

GET /pipelines/{name}/{version}

Return pipeline description.

Path parameters

▷ name

Name	Type	In	Accepted values
name (required)	string	path	Any

▷ version

Name	Type	In	Accepted values
version (required)	string	path	Any

Responses

200 - Success

application/json

Example

{
  "description": "description",
  "type": "GStreamer",
  "parameters": {
    "key": {
      "default": ""
    }
  }
}

POST /pipelines/{name}/{version}

Start new pipeline instance. Four sections are supported by default: source, destination, parameters, and tags. These sections have special handling based on the default schema and/or the schema defined in the pipeline.json file for the requested pipeline.

Path parameters

▷ name

Name	Type	In	Accepted values
name (required)	string	path	Any

▷ version

Name	Type	In	Accepted values
version (required)	string	path	Any

Request body

application/json

Example

{
  "source": {
    "type": "uri",
    "uri": "file:///root/video-examples/example.mp4"
  },
  "destination":{},
  "parameters": {},
  "tags": {}
}

Responses

200 - Success

DELETE /pipelines/{instance_id}

Stop pipeline instance.

Path parameters

▷ instance_id

Name	Type	In	Accepted values
instance_id (required)	string	path	Any

Responses

200 - Success

DELETE /pipelines/{name}/{version}/{instance_id}

Stop pipeline instance.

Path parameters

▷ name

Name	Type	In	Accepted values
name (required)	string	path	Any

▷ version

Name	Type	In	Accepted values
version (required)	string	path	Any

▷ instance_id

Name	Type	In	Accepted values
instance_id (required)	string	path	Any

Responses

200 - Success

GET /pipelines/{name}/{version}/{instance_id}

Return pipeline instance summary.

Path parameters

▷ name

Name	Type	In	Accepted values
name (required)	string	path	Any

▷ version

Name	Type	In	Accepted values
version (required)	string	path	Any

▷ instance_id

Name	Type	In	Accepted values
instance_id (required)	string	path	Any

Responses

200 - Success

application/json

Example

{
  "request": {
    "destination": {},
    "source": {},
    "parameters": {},
    "tags": {}
  },
  "id": 0,
  "type": "type"
}

GET /pipelines/{instance_id}

Return pipeline instance summary.

Path parameters

▷ instance_id

Name	Type	In	Accepted values
instance_id (required)	string	path	Any

Responses

200 - Success

application/json

Example

{
  "id": 0,
  "launch_command": "",
  "name": "",
  "request": {
    "destination": {},
    "source": {},
    "parameters": {},
    "tags": {}
  },
  "type": "type",
  "version": ""
}

GET /pipelines/status/{instance_id}

Return pipeline instance status.

Path parameters

▷ instance_id

Name	Type	In	Accepted values
instance_id (required)	string	path	Any

Responses

200 - Success

application/json

Example

{
  "avg_fps": 12.077234499118983,
  "elapsed_time": 12.999657154083252,
  "id": 1,
  "name": "object_detection",
  "start_time": 1640156425.2014737,
  "state": "RUNNING",
  "message": "",
  "version": "person_vehicle_bike"
}

GET /pipelines/{name}/{version}/{instance_id}/status

Return pipeline instance status.

Path parameters

▷ name

Name	Type	In	Accepted values
name (required)	string	path	Any

▷ version

Name	Type	In	Accepted values
version (required)	string	path	Any

▷ instance_id

Name	Type	In	Accepted values
instance_id (required)	string	path	Any

Responses

200 - Success

application/json

Example

{
  "start_time": 1,
  "elapsed_time": 5,
  "id": 0,
  "state": "RUNNING",
  "message": "",
  "avg_fps": 6.027456183070403
}