3diy
/
moonraker
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add JSON-RPC over HTTP documentation 

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Eric Callahan 2023-12-22 16:51:57 -05:00
parent aa16dd671b
commit 90e2ab6fcf
No known key found for this signature in database
GPG Key ID: 5A1EB336DFB4C71B
1 changed files with 59 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/web_api.md
View File

@ -1,8 +1,8 @@
# #
Most API methods are supported over the Websocket, HTTP, and MQTT Most API methods are supported over the Websocket, HTTP, and MQTT
(if configured) transports. File Transfer and `/access` requests are only (if configured) transports. File Transfer requests (upload and download)
available over HTTP. The Websocket is required to receive server generated exclusive to HTTP. The Websocket is required to receive server generated
events such as gcode responses. For information on how to set up the events such as gcode responses. For information on how to set up the
Websocket, please see the Appendix at the end of this document. Websocket, please see the Appendix at the end of this document.
@ -74,7 +74,7 @@ of a request.
### JSON-RPC API Overview ### JSON-RPC API Overview
The Websocket and MQTT transports use the [JSON-RPC 2.0](https://jsonrpc.org) The Websocket and MQTT transports use the [JSON-RPC 2.0](https://jsonrpc.org)
protocol. The Websocket transmits objects in a text frame, whereas MQTT protocol. The Websocket transmits JSON-RPC objects in a text frame, whereas MQTT
transmits them in the payload of a topic. When MQTT is configured Moonraker transmits them in the payload of a topic. When MQTT is configured Moonraker
subscribes to an api request topic. After an api request is processed Moonraker subscribes to an api request topic. After an api request is processed Moonraker
publishes the return value to a response topic. By default these topics are publishes the return value to a response topic. By default these topics are
@ -83,6 +83,9 @@ publishes the return value to a response topic. By default these topics are
unique identifier for each instance of Moonraker and defaults to the machine's unique identifier for each instance of Moonraker and defaults to the machine's
host name. host name.
In addition, most JSON-RPC methods are available via the
[JSONRPC HTTP request](#json-rpc-over-http).
An encoded request should look something like: An encoded request should look something like:
```json ```json
{ {
@ -192,12 +195,11 @@ be closed if Moonraker is restarted or shutdown.
### Unix Socket Connection ### Unix Socket Connection
All JSON-RPC APIs available over the websocket are also made available over a All JSON-RPC APIs available over the Websocket transport are also available
Unix Domain Socket. Moonraker creates the socket file at over the Unix Domain Socket connection. Moonraker creates the socket file at
`<datapath>/comms/moonraker.sock` (ie: `~/printer_data/comms/moonraker.sock`). `<datapath>/comms/moonraker.sock` (ie: `~/printer_data/comms/moonraker.sock`).
The Unix Socket does not use the websocket transport protocol, instead The Unix Socket expects UTF-8 encoded JSON-RPC byte strings. Each JSON-RPC
it expects UTF-8 encoded JSON-RPC strings. Each JSON-RPC request must be request must be terminated with an ETX character (`0x03`).
terminated with an ETX character (`0x03`).
The Unix Socket is desirable for front ends and extensions running on the The Unix Socket is desirable for front ends and extensions running on the
local machine as authentication is not necessary. There should be a small local machine as authentication is not necessary. There should be a small
@ -484,6 +486,7 @@ included.
} }
} }
``` ```
#### Request Cached Temperature Data #### Request Cached Temperature Data
HTTP request: HTTP request:
```http ```http
@ -763,6 +766,53 @@ The connected websocket's unique identifier.
} }
``` ```
#### JSON-RPC over HTTP
Exposes the JSON-RPC interface over HTTP. All JSON-RPC methods with
corresponding HTTP APIs are available. Methods exclusive to other
transports, such as [Identify Connection](#identify-connection), are
not available.
HTTP request:
```http
POST /server/jsonrpc
Content-Type: application/json
{
"jsonrpc": "2.0",
"method": "printer.info",
"id": 5153
}
```
!!! Note
If authentication is required it must be part of the HTTP request,
either using the API Key Header (`X-Api-Key`) or JWT Bearer Token.
Returns:
The full JSON-RPC response.
```json
{
"jsonrpc": "2.0",
"id": 5153,
"result": {
"state": "ready",
"state_message": "Printer is ready",
"hostname": "my-pi-hostname",
"software_version": "v0.9.1-302-g900c7396",
"cpu_info": "4 core ARMv7 Processor rev 4 (v7l)",
"klipper_path": "/home/pi/klipper",
"python_path": "/home/pi/klippy-env/bin/python",
"log_file": "/tmp/klippy.log",
"config_file": "/home/pi/printer.cfg",
}
}
```
!!! Note
This request will never return an HTTP error. When an error is
encountered a JSON-RPC error response will be returned.
### Printer Administration ### Printer Administration
#### Get Klippy host information #### Get Klippy host information
@ -4591,7 +4641,7 @@ Returns:
`ok` when complete `ok` when complete
### Rollback to the previous version #### Rollback to the previous version
HTTP request: HTTP request: