HTTP Interface

The HTTP interface implements an HTTP API to publish and retrieve messages.

Ports

For shiftr.io Cloud instances the interface is only available over the secure HTTP port 443 (HTTPS) to ensure all data is transmitted using an encrypted channel.

With shiftr.io Desktop the interface is only available over the insecure HTTP port 1884 due to the lack of a certificate. Another port is selected if the port is already in use by another application.

Endpoint

In the following examples you need to replace ENDPOINT with the URI that points to your shiftr.io Cloud instance or shiftr.io Desktop app.

For shiftr.io Cloud instances the endpoint URI is constructed as follows:

https://INSTANCE_NAME:TOKEN_SECRET@INSTANCE_DOMAIN

https is used as the scheme.
INSTANCE_NAME is the name of your instance.
TOKEN_SECRET is the tokens secret as configured in the settings panel.
INSTANCE_DOMAIN is the full domain to your instance.

With shiftr.io Desktop the endpoint URI is constructed as follows:

http://IP_OR_DOMAIN

http is used as the scheme.
IP_OR_DOMAIN is the IP address or domain of the machine running shiftr.io Desktop.

API Prefix

The API is available under the prefix broker/ that must be prepended to all requests paths.

Retrieve Message

The GET method is used to retrieve the latest published message:

curl 'ENDPOINT/broker/foo/bar'

Wildcards can also be used to retrieve messages:

curl 'ENDPOINT/broker/foo/+'

The retained query parameter may be set to get the latest retained message published matching the topic filter:

curl 'ENDPOINT/broker/foo/+?retained=true'

Publish Message

The POST method is used to publish a message:

curl -X POST 'ENDPOINT/broker/foo/bar' -d 'Hello World!'

The retained query parameter may be set to publish a retained message:

curl -X POST 'ENDPOINT/broker/foo/bar?retained=true' -d 'Hello World!'

The qos query parameter may be used to set a specific quality of service level:

curl -X POST 'ENDPOINT/broker/foo/bar?qos=2' -d 'Hello World!'

Protocol Notes

The basic authentication fields username and password are used to transmit the instance name and token secret.
As most browsers and HTTP tools interpret the wildcard # as fragments, the @ can be used instead.
The wildcard * is automatically replaced with +.

Enforced Limits

The topic length is limited to 128 characters.
The topic format is limited to letters, numbers and the following special characters: .,:;-_$/+#.
The payload size of a POST request is limited to 64 KB.

Message Ordering

Messages published by an HTTP client are guaranteed to be delivered in the order as they are published if the client waits for the OK response before publishing another message.

Client Libraries

Any available HTTP library can be used with the HTTP interface.