Users Manual

tion (Section 4.3). Accessing this entry point with a web browser lets the user explore and test the full API during
run-time using the Swagger UI (Section 8.2.4).
For actual HTTP requests, the current API version is appended to the entry point of the API, i.e., http://
<rcvisard>/api/v1. 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 (Section 8.2.2) 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://<rcvisard>/api/v1/nodes/rc
_
stereomatching'
• Get values of some of a node’s parameters using a query string
curl -X GET 'http://<rcvisard>/api/v1/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://<rcvisard>/api/v1/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://<rcvisard>/api/v1/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 re-
source is returned as JSON.
400 Bad Request A required attribute or argument of
the API request is missing or in-
valid.
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 re-
quest frequency.
The following listing shows a sample response to a successful request that accesses information about the
rc
_
stereomatching node’s minconf parameter:
8.2. REST-API interface 128