mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-11-10 07:34:11 -08:00
104 lines
3.9 KiB
Plaintext
104 lines
3.9 KiB
Plaintext
---
|
|
id: http-api
|
|
title: HTTP API
|
|
sidebar_label: HTTP API
|
|
sidebar_position: 2
|
|
---
|
|
|
|
:::info
|
|
This is a mini-spec on a HTTP API which can be used by browser based clients to interact with Meshtastic devices.
|
|
:::
|
|
|
|
## Why protobufs
|
|
|
|
- No need for JSON parsing on the resource constrained embedded server.
|
|
- Small.
|
|
- Already in use for all other transports (so shared testing/tooling coverage).
|
|
- Backwards and forward compatible.
|
|
|
|
## Request headers
|
|
|
|
- `Content-Type: application/x-protobuf`
|
|
- Indicates protobuf content (Meshtatic protobufs)
|
|
|
|
## Response headers
|
|
|
|
- `Content-Type: application/x-protobuf`
|
|
- Indicates protobuf content (Meshtatic protobufs)
|
|
- `X-Protobuf-Schema: <URI to the .proto schema file>`
|
|
- Not required but recommended for documentation/reflection purposes
|
|
|
|
## Endpoints
|
|
|
|
Two endpoints are specified:
|
|
|
|
### /api/v1/toradio
|
|
|
|
Allows `PUT` and `OPTION` requests.
|
|
|
|
#### PUT
|
|
|
|
A `PUT` request to this endpoint will be expected to contain a series of ToRadio protobuf payloads.
|
|
|
|
The protobufs will be sent in binary as the body for the request.
|
|
|
|
For the initial implementation, only one ToRadio message per request is supported, but future optimizations to improve throughput might add support for multiple ToRadios in a single request.
|
|
|
|
#### OPTIONS
|
|
|
|
An `OPTIONS`request to this endpoint will return a response status code `204` and headers only.
|
|
|
|
### /api/v1/fromradio
|
|
|
|
Allows `GET` requests.
|
|
|
|
#### GET
|
|
|
|
A `GET` request from this endpoint will return a series of FromRadio protobufs.
|
|
|
|
The protobufs will be sent in binary as the body for the request.
|
|
|
|
**Parameters**
|
|
|
|
##### **/api/v1/fromradio?all**
|
|
|
|
- `all=false` (unset default)
|
|
- Only one protobuf is returned.
|
|
- `all=true`
|
|
- All available protobufs are returned.
|
|
|
|
##### **/api/v1/fromradio?chunked**
|
|
|
|
- `chunked=false` (unset default, not yet implemented)
|
|
- The request returns all protobufs that can be delivered for the client's session (this would allow the client to poll by doing a series of requests). This is the only option that is supported in the initial release.
|
|
- `chunked=true` (not yet implemented)
|
|
- If chunked=true, the response will be a [stream of chunks](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) that the server will keep open as long as the client wants. This will allow efficient streaming of new `FromRadio` protobufs as they are generated by the radio.
|
|
|
|
## Authentication
|
|
|
|
The initial release will not have **any** user authentication. We assume access to the HTTP server is enough to establish trust.
|
|
|
|
Since authentication is also eventually needed for our other transports (TCP and eventually open BLE), we will be adding authentication **in-band**. When added in the second release there will be a new payload supported inside ToRadio for `SignIn <userid> <usersecret>`. The server will respond with a FromRadio `SignInResponse okay|fail`. Also, in the case of the REST API, that SignIn status will then be associated with the current session key. Most (all?) ToRadio packets will be ignored if the client is not signed in. Most (all?) FromRadio packets will be sent to clients that are not signed in.
|
|
|
|
## Client
|
|
|
|
### JavaScript
|
|
|
|
See: <https://github.com/meshtastic/meshtastic.js>
|
|
|
|
A reference client written in JavaScript will provide a JavaScript API for using this transport. That client will do HTTP connections, use the generated protobuf JavaScript code and provide an API that hides all of this REST plumbing. The two key methods will be `sendToRadio(packet)` and `onFromRadio(callback)`.
|
|
|
|
### Protoman
|
|
|
|
See: <https://github.com/spluxx/Protoman>
|
|
|
|
Protoman is able to interface with the Meshtastic REST API out of the box. This is useful for manual testing of the endpoints.
|
|
|
|
## Security
|
|
|
|
HTTP and HTTPS are both supported on the ESP32 using self signed certificates on HTTPS.
|
|
|
|
## Related documents
|
|
|
|
- Interesting slide pack on the concept: <https://www.slideshare.net/mokeefe/javaone-2009-ts5276-restful-protocol-buffers>
|