Protocol: nabto.http/1

The nabto.http/1 protocol allows clients to forward HTTP requests through Cambridge to configured HTTP services. This is typically used for camera management APIs, for example retrieving snapshots, changing settings or querying device status.

Open a datachannel with the protocol "nabto.http/1". The datachannel label can be picked arbitrarily:

const channel = pc.createDataChannel("http", {
    protocol: "nabto.http/1",
});

Constraints

The HTTP protocol has the following limitations:

No duplicate headers. Each header name may appear at most once in a request or response.
No chunked transfer encoding. Requests and responses must fit in a single message.
Maximum message size is 64 kB. Requests or responses exceeding this limit will result in an error.

http.listServices

Lists the HTTP services configured on the device (defined in services.http configuration tables).

Request

{
  "jsonrpc": "2.0",
  "method": "http.listServices",
  "id": "1234"
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "services": [
      {
        "name": "my_endpoint",
        "description": "A test HTTP endpoint"
      }
    ]
  },
  "id": "1234"
}

Each entry contains:

Field	Type	Description
`name`	string	Service name, used in the `service` parameter of `http.request`
`description`	string	Human-readable description from the configuration

http.request

Forwards an HTTP request to a configured service.

Request

{
  "jsonrpc": "2.0",
  "method": "http.request",
  "params": {
    "service": "my_endpoint",
    "method": "GET",
    "target": "/api/hello",
    "headers": {
      "Authorization": "Bearer token123",
      "X-Custom-Header": "value"
    },
    "body": "base64-encoded-request-body"
  },
  "id": "5678"
}

Parameters

Parameter	Required	Type	Description
`service`	Yes	string	HTTP service name from the device configuration
`method`	Yes	string	HTTP method (`GET`, `POST`, `PUT`, `DELETE`, etc.)
`target`	Yes	string	Request path (e.g., `/api/hello`)
`headers`	No	object	Request headers as key-value pairs
`body`	No	string	Base64-encoded request body

Response

{
  "jsonrpc": "2.0",
  "result": {
    "status": 200,
    "headers": {
      "content-type": "application/json",
      "x-custom-response": "value"
    },
    "body": "base64-encoded-response-body"
  },
  "id": "5678"
}

Field	Type	Description
`status`	number	HTTP status code
`headers`	object	Response headers as key-value pairs
`body`	string (optional)	Base64-encoded response body, omitted if empty

http.cancel

Cancels an in-flight HTTP request. This is a JSON-RPC notification, so no response is sent. The params value is the id of the request to cancel.

{
  "jsonrpc": "2.0",
  "method": "http.cancel",
  "params": "5678"
}

If the cancelled request has not yet completed, the original request will return a JSON-RPC error with code -32001.

Error Codes

In addition to standard JSON-RPC errors, the HTTP protocol defines:

Code	Message	Description
`-32000`	Generic error	An error occurred, more information can be found in the `description` field of the error object
`-32001`	Request cancelled	The request was cancelled by an `http.cancel` notification
`-32002`	Service not found	Requested service is not configured on the device
`-32003`	Gateway timeout	Could not connect to upstream or request timed out
`-32004`	Response too large	The HTTP response exceeded the 256 kB maximum message size