From efeea0d8e1d84e8201997a58c58274c79d8601b2 Mon Sep 17 00:00:00 2001 From: Eric Callahan Date: Fri, 4 Mar 2022 19:56:13 -0500 Subject: [PATCH] docs: document connection identify endpoint Signed-off-by: Eric Callahan --- README.md | 2 +- docs/api_changes.md | 8 ++++ docs/web_api.md | 89 +++++++++++++++++++++++++++++++++++---------- 3 files changed, 78 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 46c238e..52de788 100644 --- a/README.md +++ b/README.md @@ -46,4 +46,4 @@ Users:\ [user_changes.md](https://moonraker.readthedocs.io/en/latest/user_changes/) - Febuary 22nd 2022 Developers:\ -[api_changes.md](https://moonraker.readthedocs.io/en/latest/api_changes/) - March 15th 2021 +[api_changes.md](https://moonraker.readthedocs.io/en/latest/api_changes/) - March 4th 2022 diff --git a/docs/api_changes.md b/docs/api_changes.md index 5509354..c16e2b7 100644 --- a/docs/api_changes.md +++ b/docs/api_changes.md @@ -1,6 +1,14 @@ ## This document keeps a record of all changes to Moonraker's web APIs. +### March 4th 2022 +- Moonraker API Version 1.0.1 +- The `server.websocket.id` endpoint has been deprecated. It is + recommended to use `server.connection.idenitfy` method to identify + your client. This method returns a `connection_id` which is + the websocket's unique id. See + [the documentation](web_api.md#identify-connection) for details. + ### May 8th 2021 - The `file_manager` has been refactored to support system file file events through `inotify`. Only mutable `roots` are monitored, diff --git a/docs/web_api.md b/docs/web_api.md index e7b65de..8c05cc9 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -169,6 +169,75 @@ on_release: ### Printer Administration +#### Identify Connection +This method provides a way for persistent clients to identify +themselves to Moonraker. This information may be used by Moonraker +perform an action or present information based on if a specific +client is connected. Currently this method is only available +to websocket connections. + +HTTP request: `Not Available` + +JSON-RPC request (Websocket Only): +```json +{ + "jsonrpc": "2.0", + "method": "server.connection.idenity", + "params": { + "client_name": "moontest", + "version": "0.0.1", + "type": "web", + "url": "http://github.com/arksine/moontest" + }, + "id": 4656 +} +``` + +All parameters are required. Below is an explanation of each parameter. + +- `client_name`: The name of your client, such as `Mainsail`, `Fluidd`, + `KlipperScreen`, `MoonCord`, etc. +- `version`: The current version of the connected client +- `type`: Application type. May be one of `web`, `mobile`, `desktop`, + `display`, `bot`, or `other`. These should be self explanatory, use + `other` if your client does not fit any of the prescribed options. +- `url`: The url for your client's homepage + +Returns: + +The connection's unique identifer. +```json +{ + "connection_id": 1730367696 +} +``` + +#### Get Websocket ID + +!!! Warning + This method is deprecated. Please use the + [identify endpoint](#identify-connection) to retreive the + Websocket's UID + +HTTP request: `Not Available` + +JSON-RPC request (Websocket Only): +```json +{ + "jsonrpc": "2.0", + "method": "server.websocket.id", + "id": 4656 +} +``` +Returns: + +The connected websocket's unique identifer. +```json +{ + "websocket_id": 1730367696 +} +``` + #### Get Klippy host information HTTP Request: @@ -692,26 +761,6 @@ is returns, the server will restart. Any existing connection will be disconnected. A restart will result in the creation of a new server instance where the configuration is reloaded. -#### Get Websocket ID -HTTP request: `Not Available` - -JSON-RPC request: -```json -{ - "jsonrpc": "2.0", - "method": "server.websocket.id", - "id": 4656 -} -``` -Returns: - -The connected websocket's unique identifer. -```json -{ - "websocket_id": 1730367696 -} -``` - ### GCode APIs #### Run a gcode: