HTTP API Revision as of 11:55, 7 April 2022 by R3ABM (Talk | contribs) (diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Since version BrandMeister 20190421-185653 has built-in web server.

Embedded web server provides several services such as:

• status - represent some method of Status API
• service - implements several methods to send SMS and telemetry or make a call with AMBE file
• health - monitoring of embedded components compatible with Consul Health API

Detection of entry point

system.php and remote.php at Status API provide a data of entry point for HTTP API. Please check "remote" object. Port parameter corresponds to TCP port and ‘'Secure'’ indicates using of HTTPS (or HTTP).

Status API

• /status/system.json
• /status/status.json
• /status/list.json
• /status/terminal.json
• /status/status.msgpack
• /status/list.msgpack
• /status/terminal.msgpack

.json methods implement fully the same structure of data as .php version. .msgpack methods have MeasagePack-encoded data in the same order as .json version. Please check info about General Status API (.php) at Status API. This API supports zlib compression requested by Accept-Encoding: deflate.

Service API

This service API requires to use HTTP Digest Authentication, where username is an registered application ID. All requests should be sent as HTTP POST method having type application/x-www-form-urlencoded or application/form-data In case of success server returns HTTP code 200 or 500 in case of failure.

/service/call - play voice call

source - ID to be used as a source
destination - ID of destination station or group
type - private or announce (for a group call)
data - attached file in plain format of AMBE mode 33 (.ambe) or DSD (.amb)

/service/message - send text message

source - ID to be used as a source
destination - ID of destination station or group
type - private or announce (for group message)
text - message text in UTF-8
interval - long-poll timeout in milliseconds (optional)

Long-polling mode responds to get a status of message delivery (check section Long-polling):

• { "status": 8 } - Success
• { "status": 64 } and greater - some kind of delivery error

/service/telemetry - set state

source - ID to be used as a source
destination - ID of destination station or group
output1 ... output8 - command for each output (same as MQTT API): 0 = None, 20 = Clear, 21 = Set, 22 = Toggle, 23 = Pulse

/service/telemetry - query state

source - ID to be used as a source
destination - ID of destination station or group
interval - long-poll timeout in milliseconds

/service/presence - query state

source - ID to be used as a source
destination - ID of destination station or group
interval - long-poll timeout in milliseconds

/service/location - query location

source - ID to be used as a source
destination - ID of destination station or group
interval - long-poll timeout in milliseconds

Long-polling

In case of long-polling mode, the API will always answer with HTTP code 200, and then slowly transmit response:

• Keep-alive chunks - space character
• Final message (JSON):
  • { "result": "success" }
  • { "result": "failure" }
  • { "status": xxx } - in case of simple numeric answer, such as SMS delivery report
  • { xxx } - in case of complex content

Health API

Objects list is available via system.php and D-BUS API.

/health/<object> or /health/<object>?action=check

Health check compatible with Consul:

• Code 200 - OK
• Code 429 - Temporary unavailable (too many connections, overflow, not active, etc.)
• Code 404 - Not available

/health/<object>?action=measure

Detailed metric information in JSON format

Example

• /health/APRSGate?action=measure
• /health/PushStick?action=measure
• /health/SpiderStore?action=measure