mudhorn/meshtastic
1
0
Fork 0
mirror of https://github.com/meshtastic/meshtastic.git synced 2025-01-30 15:20:45 -08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

revisions to http-api

Browse source
This commit is contained in:
sigmahour 2022-10-01 10:49:28 -04:00
parent 41ac3924d6
commit df57102e3e
1 changed files with 15 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
docs/developers/Firmware/http-api.mdx
View file

@ -5,7 +5,7 @@ sidebar_label: HTTP API
--- ---
:::info :::info
This is a mini-spec on a HTTP API which can be used by browser based clients to do operations with devices. This is a mini-spec of the HTTP REST API which can be used by browser based clients to interact with Meshtastic devices.
::: :::
## Why protobufs ## Why protobufs
@ -17,18 +17,19 @@ This is a mini-spec on a HTTP API which can be used by browser based clients to
## Request headers ## Request headers
- Content-Type: `application/x-protobuf` - `Content-Type: application/x-protobuf`
- Indicates Meshtatics protobufs - Indicates protobuf content (Meshtatic protobufs)
- Cookie: `session=ABAD1D` (not yet implemented) - `Cookie: session=ABAD1D` (not yet implemented)
- Added automatically by the browser client. - Added automatically by the browser client.
## Response headers ## Response headers
- Content-Type: `application/x-protobuf` - `Content-Type: application/x-protobuf`
- Indicates Meshtatics protobufs - Indicates protobuf content (Meshtatic protobufs)
- X-Protobuf-Schema: _<URI to the .proto schema file>_ - `X-Protobuf-Schema: <URI to the .proto schema file>`
- Not required but recommended for documentation/reflection purposes - Not required but recommended for documentation/reflection purposes
- Set-Cookie: `session=ABAD1D;path=/` (not yet implemented, consider security implications of `path=/`) - `Set-Cookie: session=ABAD1D;path=/` (not yet implemented)
<!-- - Consider the security implications of using `path=/` - cookie will be accessible from any path on the same domain.-->
- All client requests that did not include a session cookie will be assigned a random and unique session key. The cookie will not be set if the client already has one. - All client requests that did not include a session cookie will be assigned a random and unique session key. The cookie will not be set if the client already has one.
## Endpoints ## Endpoints
@ -37,6 +38,8 @@ Two endpoints are specified:
### /api/v1/toradio ### /api/v1/toradio
Allows `PUT` and `OPTION` requests.
#### PUT #### PUT
A `PUT` request to this endpoint will be expected to contain a series of ToRadio protobuf payloads. A `PUT` request to this endpoint will be expected to contain a series of ToRadio protobuf payloads.
@ -51,6 +54,8 @@ An `OPTIONS`request to this endpoint will return a response status code `204` an
### /api/v1/fromradio ### /api/v1/fromradio
Allows `GET` requests.
#### GET #### GET
A `GET` request from this endpoint will return a series of FromRadio protobufs. A `GET` request from this endpoint will return a series of FromRadio protobufs.
@ -73,7 +78,7 @@ The protobufs will be sent in binary as the body for the request.
## Authentication ## Authentication
The initial release will not have **any** user authentication. i.e. we assume access to the HTTP server is enough to establish trust. 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. 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.
@ -83,7 +88,7 @@ Since authentication is also eventually needed for our other transports (TCP and
See: <https://github.com/meshtastic/meshtastic.js> 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)". 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 ### Protoman