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
(if configured) transports. File Transfer and `/access` requests are only
available over HTTP. The Websocket is required to receive server generated
(if configured) transports. File Transfer requests (upload and download)
exclusive to HTTP. The Websocket is required to receive server generated
events such as gcode responses. For information on how to set up the
Websocket, please see the Appendix at the end of this document.
@ -74,7 +74,7 @@ of a request.
### JSON-RPC API Overview
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
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
@ -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
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:
```json
{
@ -192,12 +195,11 @@ be closed if Moonraker is restarted or shutdown.
### Unix Socket Connection
All JSON-RPC APIs available over the websocket are also made available over a
Unix Domain Socket. Moonraker creates the socket file at
All JSON-RPC APIs available over the Websocket transport are also available
over the Unix Domain Socket connection. Moonraker creates the socket file at
`<datapath>/comms/moonraker.sock` (ie: `~/printer_data/comms/moonraker.sock`).
The Unix Socket does not use the websocket transport protocol, instead
it expects UTF-8 encoded JSON-RPC strings. Each JSON-RPC request must be
terminated with an ETX character (`0x03`).
The Unix Socket expects UTF-8 encoded JSON-RPC byte strings. Each JSON-RPC
request must be terminated with an ETX character (`0x03`).
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
@ -484,6 +486,7 @@ included.
}
}
```
#### Request Cached Temperature Data
HTTP request:
```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
#### Get Klippy host information
@ -4591,7 +4641,7 @@ Returns:
`ok` when complete
### Rollback to the previous version
#### Rollback to the previous version
HTTP request: