Nimble REST API (v1)

Download OpenAPI specification:Download

Nimble's REST API (Application Programming Interface) enables users to configure and query analytics workloads executing within Nimble. Behind this API is a software layer that routes data, arbitrates resources and executes Deep Learning and analytics functions to enable enriched business insights at world-class speed.

The latest online documentation can be found here.

What is a REST API?

API is short for "Application Programming Interface". An API is a set of rules that lets programs talk to each other, exposing data and functionality across the Internet in a consistent format.

REST stands for "Representational State Transfer". This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term "REST API", they are generally referring to an API accessed using the HTTP protocol at a predefined set of URLs.

These URLs represent various resources - any information or content accessed at that location, which can be returned as JSON, HTML, or media files. Often resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT, PATCH, and DELETE. The action represented by the first and last of these is clear, but POST, PUT, and PATCH have specific meanings. How they are defined is confusing, but the general rule is: use POST to create resources, PUT to update resources, and PATCH to modify resources.

The Key Elements of Nimble

Nimble and the REST API have six key elements: Configuration, Source, Sink, Pipeline, Channel, and Stream.
A Configuration is a collection of Sources, Sinks and Pipeline Elements arranged to execute the desired analytic behavior.
A Source brings data into Nimble.
A Sink pushes data out of Nimble.
A Pipeline is made up of processing elements that perform some analytics task.
Since a Source can be shared between multiple Pipelines, a Channel is an abstraction of both a Source and a Pipeline that can be thought of as "the data brought in by this Source is operated on by this Pipeline".
A Stream is a proxied fMP4 video stream from a Source.

Configuration

Nimble is controlled by a Configuration. A Configuration is a collection of Sources, Sinks and Pipeline Elements arranged to execute the desired analytic behaviour.

Fetch the Configuration

Retrieve the Configuration from Nimble.

Responses

Response samples

200

Content type

application/json

{"sources": [{"id": 0,
"type": "file",
"address": "input.mp4",
"rate": 30
},
{"id": 1,
"type": "video",
"address": "rtsp://localhost:554/axis-media/media.amp",
"rate": 25
}
],
"sinks": [{"id": 0,
"type": "video",
"address": "output.mp4",
"filter": [1
]
},
{"id": 1,
"type": "zmq",
"address": "tcp://*:22952",
"filter": [ ]
}
],
"pipelines": [{"id": 0,
"elements": ["person-detection-0200:a:0.3:0.3",
"social-distancing:0.2"
],
"usecase": "physical-distancing",
"sources": [0,
1
],
"sinks": [0,
1
]
}
]
}

Deploy a Configuration

Deploy a Configuration to Nimble.

Request Body schema: application/json

The new Configuration in list-based format, see config.yaml.

Array

required	Array of objects non-empty [ items ]
	Array of objects[ items ]
	Array of strings or objects non-empty [ items ]
	string or null

Responses

Request samples

Payload

Content type

application/json

Example

Deployment with short-form pipeline elements

[{"sources": [{"type": "youtube",
"address": "https://youtu.be/jY86pXeTOLw",
"rate": 30
}
],
"sinks": [{"type": "zmq",
"address": "tcp://*:22952",
"filter": [ ]
}
],
"pipeline": ["person-detection-0200:a:0.3:0.3",
"social-distancing:0.2"
],
"usecase": "physical-distancing"
}
]

Source

A Source brings in data and pushes it to one or more Pipelines. Sources are generally URLs to video streams or other media but can also be other Nimble instances or files for offline processing.

Fetch all Sources

Retrieve all Sources in the Configuration.

Responses

Response samples

200

Content type

application/json

[{"id": 0,
"type": "file",
"address": "input.mp4",
"rate": 30
},
{"id": 1,
"type": "video",
"address": "rtsp://localhost:554/axis-media/media.amp",
"rate": 25
}
]

Create a Source

Create a Source in the Configuration.

header Parameters

object

Examples:

return=minimal - Request minimal response (ID only)
return=representation - Request full representational response

The preferred response (minimal or full)

Request Body schema: application/json

The new Source.

type required	string (type) Enum: "video" "file" "youtube" "zmqinternal" "zmq" "inf"
required	string or object (address)
rate	number <float> (rate) > 0

Responses

Request samples

Payload

Content type

application/json

{"type": "video",
"address": "rtsp://localhost:554/axis-media/media.amp",
"rate": 25
}

Response samples

200
201

Content type

application/json

{"id": 0,
"type": "video",
"address": "rtsp://localhost:554/axis-media/media.amp",
"rate": 25
}

Fetch a Sources information

Retrieve all of the information about a Source (by ID) in the Configuration.

path Parameters

id

required

integer <int32> (id) >= 0

The ID of the Source.

Responses

Response samples

200

Content type

application/json

{"type": "video",
"address": "rtsp://localhost:554/axis-media/media.amp",
"rate": 25
}

Update a Source

Update a Source (by ID) in the Configuration.

path Parameters

id

required

integer <int32> (id) >= 0

The ID of the Source.

header Parameters

object

Examples:

return=minimal - Request minimal response (ID only)
return=representation - Request full representational response

The preferred response (minimal or full)

Request Body schema: application/json

The Source's information.

type required	string (type) Enum: "video" "file" "youtube" "zmqinternal" "zmq" "inf"
required	string or object (address)
rate	number <float> (rate) > 0

Responses

Request samples

Payload

Content type

application/json

{"type": "file",
"address": "input.mp4",
"rate": 30
}

Response samples

200

Content type

application/json

{"type": "file",
"address": "input.mp4",
"rate": 30
}

Modify a Source

Modify a Source (by ID) in the Configuration.
JSON merge patch (RFC7386) is used to apply the modifications to the Source's information.

path Parameters

id

required

integer <int32> (id) >= 0

The ID of the Source.

header Parameters

object

Examples:

return=minimal - Request minimal response (ID only)
return=representation - Request full representational response

The preferred response (minimal or full)

Request Body schema: application/merge-patch+json

The Source's information

type	string (type) Enum: "video" "file" "youtube" "zmqinternal" "zmq" "inf"
	string or object (address)
rate	number <float> (rate) > 0

Responses

Request samples

Payload

Content type

application/merge-patch+json

{"type": "file",
"address": "input.mp4"
}

Response samples

200

Content type

application/json

{"type": "file",
"address": "input.mp4",
"rate": 25
}

Delete a Source

Delete a Source (by ID) in the Configuration.

path Parameters

id

required

integer <int32> (id) >= 0

The ID of the Source.

query Parameters

force

boolean

Default: false

Whether to force deletion of the Source even if it is being referenced by a Pipeline. If true, the Source will be automatically removed from any Pipelines that reference it.

Responses

Response samples

409

Content type

application/json

{"pipelines": [0,
1
]
}

Fetch a Sources statistics

Retrieve all the runtime statistics for a Source (by ID) in the Configuration.

path Parameters

id

required

integer <int32> (id) >= 0

The ID of the Source.

Responses

Response samples

200

Content type

application/json

{"status": "starting",
"fps": 0,
"latency": 0
}

Sink

A Sink takes data from a Pipeline and pushes it out. Apart from the WebSocket API, which is always active and can be found here, other Sinks such has ZMQ sockets or file can be created.

Fetch all Sinks

Retrieve all Sinks in the Configuration.

Responses

Response samples

200

Content type

application/json

[{"id": 0,
"type": "video",
"address": "output.mp4",
"filter": [1
]
},
{"id": 1,
"type": "zmq",
"address": "tcp://*:22952",
"filter": [ ]
}
]

Create a Sink

Create a Sink in the Configuration.

header Parameters

object

Examples:

return=minimal - Request minimal response (ID only)
return=representation - Request full representational response

The preferred response (minimal or full)

Request Body schema: application/json

The Sink.

type required	string (sink_type) Enum: "file" "embedding" "zmq" "zmqinternal" "inf"
address required	string <url> (sink_address)
filter	Array of integers <int32> (filter) unique [ items <int32 > >= 0 ] A list of sources to include. An empty list indicates no filtering is enabled.

Responses

Request samples

Payload

Content type

application/json

{"type": "video",
"address": "output.mp4"
}

Response samples

200
201

Content type

application/json

{"id": 0,
"type": "video",
"address": "output.mp4",
"filter": [ ]
}

Fetch a Sinks information

Retrieve all of the information about a Sink (by ID) in the Configuration.

path Parameters

id

required

integer <int32> (sink_id) >= 0

The ID of the Sink.

Responses

Response samples

200

Content type

application/json

{"type": "zmq",
"address": "tcp://*:22952",
"filter": [ ]
}

Update a Sink

Update a Sink (by ID) in the Configuration.

path Parameters

id

required

integer <int32> (sink_id) >= 0

The ID of the Sink.

header Parameters

object

Examples:

return=minimal - Request minimal response (ID only)
return=representation - Request full representational response

The preferred response (minimal or full)

Request Body schema: application/json

The Sink's information.

type required	string (sink_type) Enum: "file" "embedding" "zmq" "zmqinternal" "inf"
address required	string <url> (sink_address)
filter	Array of integers <int32> (filter) unique [ items <int32 > >= 0 ] A list of sources to include. An empty list indicates no filtering is enabled.