General API structure

The general entry point to the rc_visard’s API is http://<host>/api/, where <host> is either the device’s IP address or its host name as known by the respective DHCP server, as explained in network configuration. Accessing this entry point with a web browser lets the user explore and test the full API during run-time using the Swagger UI .

For actual HTTP requests, the current API version is appended to the entry point of the API, i.e., http://<host>/api/v2. All data sent to and received by the REST-API follows the JavaScript Object Notation (JSON). The API is designed to let the user create, retrieve, modify, and delete so-called resources as listed in Available resources and requests using the HTTP requests below.

Request type	Description
GET	Access one or more resources and return the result as JSON.
PUT	Modify a resource and return the modified resource as JSON.
DELETE	Delete a resource.
POST	Upload file (e.g., license or firmware image).

Depending on the type and the specific request itself, arguments to HTTP requests can be transmitted as part of the path (URI) to the resource, as query string, as form data, or in the body of the request. The following examples use the command line tool curl, which is available for various operating systems. See https://curl.haxx.se.

• Get a node’s current status; its name is encoded in the path (URI)

  curl -X GET 'http://<host>/api/v2/pipelines/0/nodes/rc_stereomatching'
  

• Get values of some of a node’s parameters using a query string

  curl -X GET 'http://<host>/api/v2/pipelines/0/nodes/rc_stereomatching/parameters?name=minconf&name=maxdepth'
  

• Configure a new datastream; the destination parameter is transmitted as form data

  curl -X PUT --header 'Content-Type: application/x-www-form-urlencoded' -d 'destination=10.0.1.14%3A30000' 'http://<host>/api/v2/datastreams/pose'
  

• Set a node’s parameter as JSON-encoded text in the body of the request

  curl -X PUT --header 'Content-Type: application/json' -d '[{"name": "mindepth", "value": 0.1}]' 'http://<host>/api/v2/pipelines/0/nodes/rc_stereomatching/parameters'
  

As for the responses to such requests, some common return codes for the rc_visard’s API are:

Status Code	Description
200 OK	The request was successful; the resource is returned as JSON.
400 Bad Request	A required attribute or argument of the API request is missing or invalid.
404 Not Found	A resource could not be accessed; e.g., an ID for a resource could not be found.
403 Forbidden	Access is (temporarily) forbidden; e.g., some parameters are locked while a GigE Vision application is connected.
429 Too many requests	Rate limited due to excessive request frequency.

The following listing shows a sample response to a successful request that accesses information about the rc_stereomatching node’s minconf parameter:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 157

{
    "name": "minconf",
    "min": 0,
    "default": 0,
    "max": 1,
    "value": 0,
    "type": "float64",
    "description": "Minimum confidence"
}

Note

The actual behavior, allowed requests, and specific return codes depend heavily on the specific resource, context, and action. Please refer to the rc_visard’s available resources and to each software module’s parameters and services.

Migration from API version 1

API version 1 has become deprecated with the 22.01 firmware release of the rc_visard. The following changes were introduced in API version 2.

• All 3D-camera, navigation, detection and configuration modules which were located under /nodes in API version 1 are now under /pipelines/0/nodes/, e.g. /pipelines/0/nodes/rc_camera.

• Configuring load carriers, grippers and regions of interest is now only possible in the global database modules, which are located under /nodes, e.g. /nodes/rc_load_carrier_db. The corresponding services in the detection modules have been removed or deprecated.
• Templates can now be accessed under /templates, e.g. /templates/rc_silhouettematch.

Available resources and requests

The available REST-API resources are structured into the following parts:

• /nodes

  Access the rc_visard’s global Database modules with their run-time status, parameters, and offered services, for storing data used in multiple modules, such as load carriers, grippers and regions of interest.

• /pipelines

  Access to the status and configuration of the camera pipelines. There is always only one camera pipeline with number 0.

• /pipelines/0/nodes

  Access the rc_visard’s 3D-camera, navigation, detection and configuration software modules with their run-time status, parameters, and offered services.

• /templates

  Access the object templates on the rc_visard.

• /datastreams

  Access and manage data streams of the rc_visard’s rc_dynamics interface.

• /system

  Access the system state, set network configuration, and manage licenses as well as firmware updates.

• /logs

  Access the log files on the rc_visard.