HTTP V2

The (V2) HTTP component connects the DroneDeploy Robotics Agent to one or more HTTP endpoints, allowing you to integrate your robot which uses HTTP APIs for communication. These HTTP endpoints may be exposed on the robot itself, or available on the LAN the robot is part of.

The HTTP component is bidirectional; it can both call HTTP endpoints in response to commands being send from the DroneDeploy Robotics Portal, and automatically poll HTTP endpoints in order to publish data to the Robotics Portal.

Configuration

To use the (V2) HTTP component, your agent will need a section in its agent-settings.json file which enables the http-v2 component, as shown in the example below. For more information on how to configure the agent components, see Agent Configuration.

...
"components": [
...
  {
    "enabled": true,
    "id": "http-v2",
    "settings": {
      "name": "http",
      "logLevel": 4,
	  "tls": {
		"skipVerify": false
	  },
      "apis": {
        "local": {
          "spec": {
            "openapi": "3.0.0",
            "servers": [
              {
                "url": "https://dev-api.rocos.io"
              }
            ],
            "paths": {
              "/time": {
                "get": {
                  "summary": "Gets the time."
                }
              }
            }
          }
        },
        "remote": {
          "spec": "https://dev-api.rocos.io/api-docs-time-syncer/doc.json"
        }
      }
    }
  },
...
]

Top Level Configuration Properties

Name	Description	Default
logLevel	The logging verbosity: 1 - very quiet, 6 - very talkative.	4
tls	Optional properties object for configuration of TLS/SSL functionality. Refer below.	Refer below.
apis	Optional properties object for configuration of HTTP APIs to use. Refer below.	Refer below.

TLS Configuration Properties

Caution

Make sure you are aware of the security implications before changing TLS and other security related functionality.

The TLS configuration object allows modification of the default behaviour used by the component when using TLS/SSL to establish connections to HTTP endpoints. TLS functionality configured in this way will affect all connections to HTTP endpoints made by the component. If you need to use different TLS configuration for some endpoints, you will need to create a second instance of the HTTP component.

Name

Description

skipVerify

When set to true, the HTTP component will not verify the authenticity of certificates provided by each HTTP server. It is common that some robots will expose HTTPS endpoints using self-signed certificates: these certificates cannot be verified, in which case TLS certificate verification will need to be disabled in order to connect to these endpoints via TLS. The default is false, meaning that TLS certificates will be verified as normal.

API Configuration Properties

The API configuration object allows you to define a number of 'API' surfaces, which the HTTP component will expose so they may be called remotely from the DroneDeploy Robotics Portal. APIs are defined based on OpenAPI specifications, either V2 (a.k.a. Swagger) or V3; the component does not provide complete support for all OpenAPI specification elements - only a limited subset of the specification is supported - contact DroneDeploy Support for further information.

The apis object should contain one property for each API to be exposed, where the name of the property is the name of the resulting API, and the value of the property is an object of the form:

{
	"spec":...,
	"pathParams":{...},
	"creds":{...}
}

Specification Property

The property spec is mandatory, and may be either a string, or an object. This property defines which HTTP APIs will be exposed by the component.

If the spec property is a string, then it should contains either a relative or absolute URL.

If the string is a relative URL (i.e. a path to a local file), then it should point to a JSON or YAML file which contains a valid and fully-defined OpenAPI specification (V2, V3 and V3.1 formats are supported).

If the string is an absolute URL, then it should point to a JSON or YAML files which contains a valid and fully-defined OpenAPI specification (V2, V3 and V3.1 formats are supported). If the endpoint which is pointed to requires authentication, then credentials must be provided via the creds property (refer below).

If the spec property is an object, then it should be the direct JSON representation of the OpenAPI specification for the API (only V3 and V3.1 formats are supported in this case). The specification must contain a servers property with a single entry. A simple example of an OpenAPI specification being included directly in the configuration is as follows:

...
"spec": {
            "openapi": "3.0.0",
            "servers": [
              {
                "url": "https://dev-api.rocos.io"
              }
            ],
            "paths": {
              "/time": {
                "get": {
                  "summary": "A description is required, because the method property must be non-empty in order for parsing to succeed."
                }
              }
            }
          }
...

Path Parameters Property

The property pathParams is optional. If present, it should be an object where each property is an array of strings, such as shown here:

{
	"param1": ["1.1", "1.2", "1.3"],
	"param2": ["2.1", "2.2"]
}

Refer to the API Parameterization section below on how these values are then used in expansion of the API specification.

Credentials Property

The property creds is optional. If present, it should be an object with one of two possible forms:

Either:

{
	"user": "$USERNAME",
	"pass": "$PASSWORD"
}

or

{
	"bearer": "$TOKEN"
}

In the former case, the component will use basic authentication when invoking endpoints from the API, using the provided (plaintext) username and password. Basic authentication is always passed via the Authorization header.

In the latter case, the component will use bearer authentication when invoking endpoints from the API, using the provided bearer token. Only header based bearer authentication is supported at the present time; query based authentication is not supported.

Data Model

Default Data Model

The component always exposes a set of services which can be used to perform arbitrary HTTP requests:

Service	Description
/http/call()	Calls an HTTP endpoint using the method type specified in the request.
/http/call/get()	Calls an HTTP endpoint using the GET method.
/http/call/patch()	Calls an HTTP endpoint using the PATCH method.
/http/call/post()	Calls an HTTP endpoint using the POST method.
/http/call/put()	Calls an HTTP endpoint using the PUT method.

The service request format for each service is the same, with the exception that only call() includes the property method:

{
  "method": "",
  "address": "",
  "headers": {},
  "body": ""
}

Response Encoding

The service response will, by default, using JSON encoding. Alternative encodings can be obtained by invoking the service using the enc query parameter: calling /http/call?enc=JSON will also encode the response to JSON, other supported encodings are CBOR and RAW. Note that generally specifying these other encodings will only be useful in the case of invoking the service via SDKs, since generally the DroneDeploy Robotics Portal only operates on JSON encoded messages.

A response encoded in RAW format will be delivered exactly as it is delivered by the HTTP endpoint. For JSON encoded responses, the HTTP component will attempt to apply some heuristics to obtain useful JSON output: if the response header specifies that the content type is application/json, or the response body successfully validates as JSON, the response body will be returned as is; else, if the response body contains no non-printing characters it will be returned enclosed in quotes as a JSON string; otherwise it will be base64 encoded and returned as a JSON string. There is similar behaviour for CBOR response encoding.

API Data Model

For each API whose specification is parsed successfully from the configuration, the component will expose a number of services and telemetry topics which correspond to the paths defined in the API specification.

For each supported HTTP method $METHOD of the API path $PATH, the component will advertise a service /http/apis/$API/$PATH/$METHOD(). Each service will have a request of the form:

{
	"query":{},
	"path":{},
	"headers":{},
	"body": ...
}

Where the body property will automatically be populated according to the JSON schema described in the API specification. APIs which have non-JSON request body formats are not supported. When the service is invoked, the HTTP request will automatically be constructed from the service request, using any authentication credentials which were included in the API configuration. The service may be called using the enc query parameter to control the response encoding, the same as for the generic call() service exposed by the component (as described above).

In addition to the services which are exposed, if the path supports the HTTP GET method, a telemetry topic /http/apis/$API/$PATH will also be exposed by the component. Subscribing to this topic causes the component to poll the HTTP endpoint in order to generate a telemetry stream from the responses. The topic maybe subscribed to using the enc query parameter to control the message encoding; the default encoding will be JSON.

By default, the component will poll the HTTP endpoint at 1Hz. The polling rate can be controlled by using the int query parameter, e.g. a query parameter of int=100ms will poll the topic at an interval of 100ms, thus generating telemetry messages at approximately 10Hz. The component will not begin each new HTTP request until the previous request for that topic has completed; thus, setting the interval to a value lower than the round-trip-time (RTT) from the agent to the endpoint server will have no effect.

API Parameterization

The OpenAPI specification allows for the use of parameterization to describe complicated APIs: some common parameterization options are supported by the HTTP component:

Server/Host Parameterization

Not supported.

Path Parameterization

When exposing services, the HTTP component supports API paths which are parameterised, in two ways.

Firstly, path parmeters, and the values thereof, maybe configured using the Path Parameters Property included in the API configuration, as described above. The property will be configured with a list of values which should be realised for each path parameter. The component will automatically expand each relevant combination of these parameter values, and expose services (and telemetry topics) for each.

For instance, if the API specification for the API test includes a path /x/{param1}/{param2}, and the following configuration is used:

"pathParams": {
	"param1":["a", "b"],
	"param2":["1", "2", "3"]
}

Then the following services would be exposed by the component:

/http/apis/test/x/a/1()
/http/apis/test/x/a/2()
/http/apis/test/x/a/3()
/http/apis/test/x/b/1()
/http/apis/test/x/b/2()
/http/apis/test/x/b/3()

Secondly, if an API path includes some parameters whose values are not defined in the Path Parameters Property for that API, then these parameters must instead be specified in the request when the service is called. The service exposed by the component will include the parameter demarked in braces as part of the data URL, and the path property of the service request will include a property for that parameter.

The following image shows a service which includes both ways of using path parameters. Services for a parameter robotName are exposed for the pre-configured values of jerry and ulysses. But the parameter mode is not pre-configured, so appears as {mode} in the data URL, and is included as a (mandatory) property in the request.

When exposing telemetry topics, the HTTP component supports API paths which are parameterised only if all the path parameter values are pre-configured. Telemetry topics will not be exposed for any paths which have path parameters whose values have not been pre-configured.

Query Parameterization

When exposing services , the HTTP component supports API paths which include query parameters, as shown below:

The names, and default values, of required queries are automatically included in the service request.

When exposing telemetry topics, the HTTP component does not support query parameters.

Request Paramaterization

Not supported.