diff --git a/docs/web_api.md b/docs/web_api.md index 25ac351..7c842f9 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -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 `/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: