moonraker/api_changes.md at 0a811b9e44ff1d4b68836f75143d26d09fad5840

17 KiB

Raw Blame History

This document keeps a record of all changes to Moonraker's web APIs.

February 17 2023

Moonraker API Version 1.2.1
An error in the return value for some file manager endpoints has been corrected. Specifically, the returned result contains an item object with a path field that was prefixed with the root (ie: "gcodes"). This is inconsistent with the websocket notification and has been corrected to remove the prefix. This affects the following endpoints:
- POST /server/files/directory | server.files.post_directory
- DELETE /server/files/directory | server.files.delete_directory
- POST /server/files/move | server.files.move
- POST /server/files/copy | server.files.copy

March 4th 2022

Moonraker API Version 1.0.1
The server.websocket.id endpoint has been deprecated. It is recommended to use server.connection.identify method to identify your client. This method returns a connection_id which is the websocket's unique id. See the documentation for details.

May 8th 2021

The file_manager has been refactored to support system file file events through inotify. Only mutable roots are monitored, (currently gcodes and config). Subfolders within these these roots are also monitored, however hidden folders are not. The following changes API changes have been made to acccommodate this functionality:
- The notify_filelist_changed actions have changed. The new actions are as follows:
  - create_file: sent when a new file has been created. This includes file uploads and copied files.
  - create_dir: sent when a new directory has been created.
  - delete_file: sent when a file has been deleted.
  - delete_dir: sent when a directory has been deleted.
  - move_file: sent when a file has moved.
  - move_dir: sent when a directory has moved.
  - modify_file: sent when an existing file has been modified
  - root_update: sent when a root directory location has been set. For example, if a user changes the gcode path in Klipper, this action is sent with a notify_filelist_changed notification.
- File list notifications for gcode files are now only sent after all metadata has been processed. Likewise, requests to copy, move, or upload a file will only return after metadata has been processed. Notifications are synced with requests so that the request should always return before the notification is sent.
- Thumbnails are now stored in the .thumbs directory to prevent changes to thumbnails from emitting filelist notications. This change will be reflected in the metadata's relative_path field, so clients that use this field should not need to take additional action. Note that existing thumbnails will remain in the thumbs directory and filelist notifications will be sent for changes to these thumbnails.
- The notify_metadata_update notification has been removed Clients
- can reliably expect metadata to be available for new or moved gcode files when a request returns.
- The return values for several endpoints have been updated. They now contain information similar to that which is pushed by the notify_filelist_changed notification.
The deprecated data field in gcode metadata has been removed. The size field now returns the size of the .png file.

March 15th 2021

The data field for gcode thumbnails is now deprecated and will be removed in the near future. Thumbnails are now saved to png files in a thumbs directory relative to a gcode file's location. This path is available in the relative_path field for each thumbnail entry in the metadata.

January 31st 2021

The GET /server/temperature_store endpoint now only returns fields that each sensor reports. For example, if a particuarly temperature sensor does not report "target" or "power", then the corresponding fields will not be reported for that sensor in response to the temperature_store request.

January 22nd 2021

The POST /machine/update/client endpoint now requires a name argument. This change added multiple client support
The response to GET /machine/update/status no longer returns a client field. Instead it will add fields matching the name of each configured client. Keep in mind that the client object could have a different set of fields depending on the type of a client. The easy way to check for this is to see if a branch field is present. If so, this client is a git repo. Otherwise it is a web client.

January 4th 2021

A notify_update_refreshed notification has been added. Moonraker now auto-refreshes the update status at roughly a 2 hour interval. When an auto-refresh is complete this notification is broadcast. Included is an object that matches the response from /machine/update/status.
The behavior of some of the update_manager APIs has changed:
- The refresh argument for /machine/update/status is now more of a suggestion than a rule. If an update or a print is in progress then the request will ignore the refresh argument and immediately return the current status. Generally speaking requesting a refresh should not be necessary with addition of auto refresh.
- The update requests (ie /machine/update/klipper) will now return an error if a print is in progress. If the requested update is in progress then the request will return valid with a message stating that the update is in progress. If another object is being updated then the request will be queued and block until it its complete.

January 1st 2021

A notify_klippy_shutdown websocket notification has been added

December 30th 2020

Some additional fields are now reported in the response to GET /machine/update/status.

November 28th 2020

The following new endpoints are available when the [update_manager] section has been configured:
- GET /machine/update/status
- POST /machine/update/moonraker
- POST /machine/update/klipper
- POST /machine/update/client
- POST /machine/update/system
The following endpoint has been added and is available as part of the core API:
- POST /machine/services/restart

See web_api.md for details on these new endpoints.

November 23rd 2020

Moonraker now serves Klipper's "docs" directory. This can be access at GET /server/files/docs/<filename>.

November 19th 2020

The path for the power APIs has changed from gpio_power to device_power:
- GET /machine/device_power/devices
  {"jsonrpc":"2.0","method":"machine.device_power.devices","id":"1"}
  Returns an array of objects listing all detected devices. Each object in the array is guaranteed to have the following fields:
  - device: The device name
  - status: May be "init", "on", "off", or "error"
  - type: May be "gpio" or "tplink_smartplug"
- GET /machine/device_power/status?dev_name
  {"jsonrpc":"2.0","method":"machine.device_power.status","id":"1", "params":{"dev_name":null}}
  It is no longer possible to call this method with no arguments. Status will only be returned for the requested device, to get status of all devices use /machine/device_power/devices. As before, this returns an object in the format of {device_name: status}, where device_name is the name of the device and status is the devices current status.
- POST /machine/device_power/on?dev_name
  {"jsonrpc":"2.0","method":"machine.device_power.on","id":"1", "params":{"dev_name":null}}
  Toggles device on. Returns the current status of the device.
- POST /machine/device_power/off?dev_name
  {"jsonrpc":"2.0","method":"machine.device_power.off","id":"1", "params":{"dev_name":null}}
  Toggles device off. Returns the current status of the device.
- The notify_power_changed notification now includes an object containing device info, matching that which would be recieved from a single item in /machine/power/devices.

November 12th 2020

Two new fields have been added to the gcode metadata:
- gcode_start_byte: Indicates the byte position in the file where the first "Gxx" or "Mxx" command is detected.
- gcode_end_byte: Indicates the byte position in the file where the last "Gxx" or "Mxx" command is detected. These fields may be used to more accurately predict print progress based on the file size.

November 11th 2020

The server.websocket.id API has been added. This returns a unique ID that Moonraker uses to track each client connection. As such, this API is only available over the websocket, there is no complementary HTTP request.
All HTTP API request may now include arguments in either the query string or in the request's body.
Subscriptions are now managed on a per connection basis. Each connection will only recieve updates for objects in which they are currently subscribed. If an "empty" request is sent, the subscription will be cancelled.
The POST /printer/object/subscribe now requires a connection_id argument. This is used to identify which connection's associated subscription should be updated. Currenlty subscriptions are only supported over the a websocket connection, one may use the id received from server.websocket.id.
The notify_klippy_ready websocket notification has been added.

November 2nd 2020

The GET /server/files/directory endpoint now accepts a new optional argument, extended. If extended=true, then the data returned for gcode files will also include extracted metadata if it exists.

October 25th 2020

The modified field reported for files and directories is no longer represented as a string. It is now a floating point value representing unix time (in seconds). This can be used to display the "last modified date" based on the client's timezone.

October 21st 2020

The /server/gcode_store endpoint no longer returns a string in the result's gcode_store field. It now returns an Array of objects, each object containing message and time fields. The time refers to a timestamp in unix time (seconds), and may be used to determine when the gcode store received the accompanying message.

September 30th 2020

Two new endpoints have been added:
- GET /server/info (server.info)
- GET /server/gcode_store (server.gcode_store) See web_api.md for details on their usage.

September 7th 2020

A new websocket API has been added, server.files.delete_file:
```
{jsonrpc: "2.0", method: "server.files.delete_file", params:
{path: "<root>/<file_name>"}, id: <request id>}
```
Where is either "gcodes" or "config", and <file_name> is the relative path to the file for deletion. For example: path: "gcodes/my_sub_dir/my_gcode_file.gcode"

September 3rd 2020

The Websocket APIs have changed for clarity. The APIs methods now use namespaces similar to those found in common programming languages. This change affects all websocket APIs, however websocket events have not changed. Below is a chart mapping the Previous API to the New API:

Previous Websocket Method	New Websocket Method
get_printer_info	printer.info
post_printer_emergency_stop	printer.emergency_stop
post_printer_restart	printer.restart
post_printer_firmware_restart	printer.firmware_restart
get_printer_objects_list	printer.objects.list
get_printer_objects_query	printer.objects.query
post_printer_objects_subscribe	printer.objects.subscribe
get_printer_query_endstops_status	printer.query_endstops.status
post_printer_gcode_script	printer.gcode.script
get_printer_gcode_help	printer.gcode.help
post_printer_print_start	printer.print.start
post_printer_print_pause	printer.print.pause
post_printer_print_resume	printer.print.resume
post_printer_print_cancel	printer.print.cancel
post_machine_reboot	machine.reboot
post_machine_shutdown	machine.shutdown
get_server_temperature_store	server.temperature_store
get_file_list	server.files.list
get_file_metadata	server.files.metadata
get_directory	server.files.get_directory
post_directory	server.files.post_directory
delete_directory	server.files.delete_directory
post_file_move	server.files.move
post_file_copy	server.files.copy

The "power" plugin APIs have changed. This affects both HTTP and Websocket APIs. They were originally added to the "/printer" path, however this adds the possibility of a naming conflict. The new APIs are as follows:
- GET /machine/gpio_power/devices : machine.gpio_power.devices
- GET /machine/gpio_power/status : machine.gpio_power.status
- POST /machine/gpio_power/on : machine.gpio_power.on
- POST /machine/gpio_power/off : machine.gpio_power.off

September 1st 2020

A new notification has been added: notify_metdata_update. This notification is sent when Moonraker parses metdata from a new upload. Note that the upload must be made via the API, files manually (using SAMBA, SCP, etc) do not trigger a notification. The notification is sent in the following format:

{jsonrpc: "2.0", method: "notify_metadata_update", params: [metadata]}

Where metadata is an object in the following format:

{
  filename: "file name",
  size: <file size>,
  modified: "last modified date",
  slicer: "Slicer Name",
  first_layer_height: <in mm>,
  layer_height: <in mm>,
  object_height: <in mm>,
  estimated_time: <time in seconds>,
  filament_total: <in mm>,
  thumbnails: [
    {
      width: <in pixels>,
      height: <in pixels>,
      size: <length of string>,
      data: <base64 string>
    }, ...
  ]
}

August 16th 2020

The structure of data returned from /printer/info (get_printer_info) has changed to the following format:

{
    state: "<klippy state>",
    state_message: "<current state message>",
    hostname: "<hostname>",
    software_version: "<version>",
    cpu_info: "<cpu_info>",
    klipper_path: "<moonraker use only>",
    python_path: "<moonraker use only>",
    log_file: "<moonraker use only>",
    config_file: "<moonraker use only>",
}

The "state" item can be one of the following:

"startup" - Klippy is in the process of starting up
"ready" - Klippy is ready
"shutdown" - Klippy has shutdown
"error" - Klippy has experienced an error during startup

The message from each state can be found in the state_message.

A webhooks printer object has been added, available for subscription or query. It includes the following items:
- state - Printer state identical to that returned from /printer/info
- state_message - identical to that returned from /printer/info

/printer/objects/status (get_printer_objects_status) has been renamed to /printer/objects/query (get_printer_objects_query). The format of the websocket request has changed, it should now look like the following:

{
    jsonrpc: "2.0",
    method: "get_printer_objects_query",
    params: {
        objects: {
          gcode: null,
          toolhead: ["position", "status"]
        }
    },
    id: <request id>
}

As shown above, printer objects are now wrapped in an "objects" parameter. When a client wishes to subscribe to all items of a printer object, they should now be set to null rather than an empty array. The return value has also changed:

{
  eventtime: <klippy time of update>,
  status: {
    gcode: {
      busy: true,
      gcode_position: [0, 0, 0 ,0],
      ...},
    toolhead: {
      position: [0, 0, 0, 0],
      status: "Ready",
      ...},
    ...}
  }

The status item now contains the requested status.

/printer/objects/subscription (post_printer_objects_subscription) is now printer/objects/subscribe (post_printer_objects_subscribe). This request takes parameters in the same format as the query. It now returns state for all currently subscribed objects (in the same format as a query). This data can be used to initialize all local state after the request completes.
Subscriptions are now pushed as "diffs". Clients will only recieve updates for subscribed items when that data changes. This requires that clients initialize their local state with the data returned from the subscription request.
The structure of data returned from /printer/objects/list has changed. It now returns an array of available printer objects:
```
{ objects: ["gcode", "toolhead", "bed_mesh", "configfile",....]}
```
The notify_klippy_state_changed notification has been removed. Clients can subscribe to webhooks and use webhooks.state to be notified of transitions to the "ready" and "shutdown" states
A notify_klippy_disconnected event has been added to notify clients when the connection between Klippy and Moonraker has been terminated. This event is sent with no parameters:
```
{jsonrpc: "2.0", method: "notify_klippy_disconnected"}
```

17 KiB Raw Blame History