Communicating with Fostrom over HTTP

Sometimes, your device's only way to communicate would be over HTTP(S), for example when ports are blocked, or opening TCP sockets is not possible.

HTTP payloads can only be sent in JSON. HTTP responses are also in JSON.

The API

METHOD   PATH                            PAYLOAD
---------------------------------------------------------------

POST     /v1/heartbeat
POST     /v1/datapoint/:schema_name      {fields}
POST     /v1/msg/:schema_name            {fields}

GET      /v1/mailbox/size
GET      /v1/mailbox/next
PUT      /v1/mailbox/ack/:msg_id
PUT      /v1/mailbox/reject/:msg_id
PUT      /v1/mailbox/requeue/:msg_id

Connecting

The HTTP API is available at:

https://device.fostrom.dev/v1/

Authentication

The following headers need to be sent with each request to authenticate the device:

X-Fleet-ID: <fleet_id>
X-Device-ID: <device_id>
X-Device-Secret: <device_secret> # starts with "FOS-"

Heartbeat

POST /v1/heartbeat

< {"ok": true}

Sending Data

POST /v1/datapoint/:schema_name
> {...fields}

< {"ok": true}

Sending Messages

POST /v1/msg/:schema_id
> {...fields}

< {"ok": true}

Get Mailbox Size

GET /v1/mailbox/size

< {"size": <mailbox_size>}

Fetch Next Message

GET /v1/mailbox/next

# Status: 200
< {"id": msg_id, "name": schema_name, "payload": {...fields}}

# or Status: 204 (Mailbox Empty)
< {}

Acknowledging a Message

PUT /v1/mailbox/ack/:msg_id

< {"ok": true}

Rejecting a Message

PUT /v1/mailbox/reject/:msg_id

< {"ok": true}

Requeueing a Message

PUT /v1/mailbox/requeue/:msg_id

< {"ok": true}

Errors

An error can occur when calling any route.

Every error contains the following response:

{"error": "<reason>"}

If the request is malformed, such as when the Fleet ID in the subdomain does not match the X-Fleet-ID header, or if the Device ID or Device Secret are missing or invalid, the response status will be 400.

If the device credential headers are not malformed, but the device either does not exist, or the device secret does not match, an Unauthorized error will be returned with status 401.

If the route wasn't found, 404 will be returned.

If some error occurs on our end while processing the request, a 500 status will be returned.