From 755549a74514b31be1dd69d3e9f66415284b1d35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Mon, 16 Dec 2013 01:47:06 +0100 Subject: [PATCH] Some further API documentation --- docs/api/connection.rst | 120 ++++++++++++++++ docs/api/fileops.rst | 293 +++++++++++++++++++++++++++++++++++++--- docs/api/general.rst | 36 ++++- docs/api/index.rst | 5 +- docs/api/printer.rst | 147 ++++++++++++++++++++ docs/conf.py | 12 +- docs/index.rst | 10 +- 7 files changed, 593 insertions(+), 30 deletions(-) create mode 100644 docs/api/connection.rst create mode 100644 docs/api/printer.rst diff --git a/docs/api/connection.rst b/docs/api/connection.rst new file mode 100644 index 00000000..c4526b75 --- /dev/null +++ b/docs/api/connection.rst @@ -0,0 +1,120 @@ +.. _sec-api-connection: + +******************* +Connection handling +******************* + +.. toctree:: + :maxdepth: 2 + +.. _sec-api-connection-current: + +Get connection settings +======================= + +.. http:get:: /api/control/connection + + Retrieve the current connection settings, including information regarding the available baudrates and + serial ports and the current connection state. + + **Example Request** + + .. sourcecode:: http + + GET /api/control/connection HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + **Example Response** + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "current": { + "state": "Operational", + "port": "/dev/ttyACM0", + "baudrate": 250000 + }, + "options": { + "ports": ["/dev/ttyACM0", "VIRTUAL"], + "baudrates": [250000, 230400, 115200, 57600, 38400, 19200, 9600], + "portPreference": "/dev/ttyACM0", + "baudratePreference": 250000, + "autoconnect": true + } + } + + :statuscode 200: No error + +.. _sec-api-connection-command: + +Issue a connection command +========================== + +.. http:post:: /api/control/connection + + Issue a connection command. Currently available command are: + + connect + Instructs OctoPrint to connect to the printer. Additional parameters are: + + * ``port``: Optional, specific port to connect to. If not set the current ``portPreference`` will be used, or if + no preference is available auto detection will be attempted. + * ``baudrate``: Optional, specific baudrate to connect with. If not set the current ``baudratePreference`` will + be used, or if no preference is available auto detection will be attempted. + * ``save``: Optional, whether to save the request's ``port`` and ``baudrate`` settings as new preferences. Defaults + to ``false`` if not set. + * ``autoconnect``: Optional, whether to automatically connect to the printer on OctoPrint's startup in the future. + If not set no changes will be made to the current configuration. + + disconnect + Instructs OctoPrint to disconnect from the printer. + + **Example Connect Request** + + .. sourcecode:: http + + POST /api/control/connection HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "connect", + "port": "/dev/ttyACM0", + "baudrate": 115200, + "save": true, + "autoconnect": true + } + + **Example Disconnect Request** + + .. sourcecode:: http + + POST /api/control/connection HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "disconnect" + } + + :json string command: The command to issue, either ``connect`` or ``disconnect`` + :json string port: ``connect`` command: The port to connect to. If left out either the existing ``portPreference`` + will be used, or if that is not available OctoPrint will attempt auto detection. Must be part + of the available ports. + :json number baudrate: ``connect`` command: The baudrate to connect with. If left out either the existing + ``baudratePreference`` will be used, or if that is not available OctoPrint will attempt + autodetection. Must be part of the available baudrates. + :json boolean save: ``connect`` command: Whether to save the supplied connection settings as the new preference. + Defaults to ``false`` if not set. + :json boolean autoconnect: ``connect`` command: Whether to attempt to automatically connect to the printer on server + startup. If not set no changes will be made to the current setting. + :statuscode 200: No error + :statuscode 400: If the selected `port` or `baudrate` for a ``connect`` command are not part of the available + options. \ No newline at end of file diff --git a/docs/api/fileops.rst b/docs/api/fileops.rst index 6d095b6b..418af000 100644 --- a/docs/api/fileops.rst +++ b/docs/api/fileops.rst @@ -4,14 +4,17 @@ File operations *************** +.. toctree:: + :maxdepth: 5 + .. _sec-api-fileops-retrieveall: Retrieve all files ================== -.. http:get:: /api/gcodefiles +.. http:get:: /api/files - Retrieve information regarding all GCODE files currently available and regarding the disk space still available + Retrieve information regarding all files currently available and regarding the disk space still available locally in the system. Returns a :ref:`Retrieve response `. @@ -20,8 +23,9 @@ Retrieve all files .. sourcecode:: http - GET /api/gcodefiles?apikey=abcdef HTTP/1.1 + GET /api/files HTTP/1.1 Host: example.com + X-Api-Key: abcdef... **Example response**: @@ -37,7 +41,7 @@ Retrieve all files "bytes": 1468987, "size": "1.4MB" "date": "2013-05-21 23:15", - "origin": "local" + "origin": "local", "gcodeAnalysis": { "estimatedPrintTime": "00:31:40", "filament": "0.79m" @@ -62,20 +66,16 @@ Retrieve all files "free": "3.2GB" } - :query apikey: The API key to use for the request, either the global one or a user specific one (see - :ref:`Authorization ` for more details) :statuscode 200: No error - :statuscode 401: If the API key is missing - :statuscode 403: If the API key is invalid .. _sec-api-fileops-retrievetarget: Retrieve files from specific origin =================================== -.. http:get:: /api/gcodefiles/(string:origin) +.. http:get:: /api/files/(string:origin) - Retrieve information regarding the GCODE files currently available on the selected `origin` and regarding the + Retrieve information regarding the files currently available on the selected `origin` and regarding the disk space still available locally in the system. Returns a :ref:`Retrieve response `. @@ -84,8 +84,9 @@ Retrieve files from specific origin .. sourcecode:: http - GET /api/gcodefiles/local?apikey=abcdef HTTP/1.1 + GET /api/files/local HTTP/1.1 Host: example.com + X-Api-Key: abcdef... **Example response**: @@ -101,7 +102,7 @@ Retrieve files from specific origin "bytes": 1468987, "size": "1.4MB" "date": "2013-05-21 23:15", - "origin": "local" + "origin": "local", "gcodeAnalysis": { "estimatedPrintTime": "00:31:40", "filament": "0.79m" @@ -119,15 +120,244 @@ Retrieve files from specific origin "free": "3.2GB" } - :param target: The target location from which to retrieve the files. Currently only ``local`` and ``sdcard`` are + :param origin: The origin location from which to retrieve the files. Currently only ``local`` and ``sdcard`` are supported, with ``local`` referring to files stored in OctoPrint's ``uploads`` folder and ``sdcard`` referring to files stored on the printer's SD card (if available). - :query apikey: The API key to use for the request, either the global one or a user specific one (see - :ref:`Authorization ` for more details) :statuscode 200: No error - :statuscode 400: If `origin` is neither ``local`` nor ``sdcard`` - :statuscode 401: If the API key is missing - :statuscode 403: If the API key is invalid + :statuscode 400: If `origin` is neither ``local`` nor ``sdcard`` or the request is otherwise invalid. + +.. _sec-api-fileops-uploadfile: + +Upload file +=========== + +.. http:post:: /api/files/(string:target) + + Upload a file to the selected `target`. + + Other than most of the other requests on OctoPrint's API which are expected as JSON, this request is expected as + ``Content-Type: multipart/form-data`` due to the included file upload. + + Returns an :ref:`Upload Response ` upon successful completion. + + **Example request** + + .. sourcecode:: http + + POST /api/files/local HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryDeC2E3iWbTv1PwMC + + ------WebKitFormBoundaryDeC2E3iWbTv1PwMC + Content-Disposition: form-data; name="file"; filename="whistle_v2.gcode" + Content-Type: application/octet-stream + + ;Generated with Cura_SteamEngine 13.11.2 + M109 T0 S220.000000 + T0 + ;Sliced at: Wed 11-12-2013 16:53:12 + ;Basic settings: Layer height: 0.2 Walls: 0.8 Fill: 20 + ;Print time: #P_TIME# + ;Filament used: #F_AMNT#m #F_WGHT#g + ;Filament cost: #F_COST# + ;M190 S70 ;Uncomment to add your own bed temperature line + ;M109 S220 ;Uncomment to add your own temperature line + G21 ;metric values + G90 ;absolute positioning + ... + ------WebKitFormBoundaryDeC2E3iWbTv1PwMC + Content-Disposition: form-data; name="select" + + true + ------WebKitFormBoundaryDeC2E3iWbTv1PwMC + Content-Disposition: form-data; name="print" + + true + ------WebKitFormBoundaryDeC2E3iWbTv1PwMC-- + + **Example response** + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "files": [ + ... + { + "name": "whistle_v2.gcode", + "bytes": 1468987, + "size": "1.4MB" + "date": "2013-05-21 23:15", + "origin": "local" + }, + ... + ], + "done": true, + "filename": "whistle_v2.gcode" + } + + :param target: The target location to which to upload the file. Currently only ``local`` and ``sdcard`` are supported + here, with ``local`` referring to OctoPrint's ``uploads`` folder and ``sdcard`` referring to + the printer's SD card. If an upload targets the SD card, it will also be stored locally first. + :form file: The file to upload, including a valid ``filename``. + :form select: Whether to select the file directly after upload (``true``) or not (``false``). Optional, defaults + to ``false``. + :form print: Whether to start printing the file directly after upload (``true``) or not (``false``). If set, `select` + is implicitely ``true`` as well. Optional, defaults to ``false``. + :statuscode 200: No error + :statuscode 400: If `target` is neither ``local`` nor ``sdcard``, no `file` is included in the request, the file is + neither a ``gcode`` nor an ``stl`` file (or it is an ``stl`` file but slicing support is + disabled) or the request is otherwise invalid. + :statuscode 403: If the upload of the file would override the file that is currently being printed + :statuscode 500: If the upload failed internally + +.. _sec-api-fileops-retrievefile: + +Retrieve a file's contents +========================== + +.. http:get:: /api/files/local/(path:filename) + + Downloads the selected file's contents. Only available for locally stored files, hence no `target` parameter. + + Will actually redirect to serve the download via a static context directly from the filesystem. + + **Example Request** + + .. sourcecode:: http + + GET /api/files/local/whistle_v2.gcode HTTP/1.1 + Host: example.com + + **Example Response** + + .. sourcecode:: http + + HTTP/1.1 302 Found + Location: /downloads/files/whistle_v2.gcode + + **Redirect Request** + + .. sourcecode:: http + + GET /downloads/files/whistle_v2.gcode HTTP/1.1 + Host: example.com + + **Redirect Response** + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/octet-stream + + ;Generated with Cura_SteamEngine 13.11.2 + M109 T0 S220.000000 + T0 + ;Sliced at: Wed 11-12-2013 16:53:12 + ;Basic settings: Layer height: 0.2 Walls: 0.8 Fill: 20 + ;Print time: #P_TIME# + ;Filament used: #F_AMNT#m #F_WGHT#g + ;Filament cost: #F_COST# + ;M190 S70 ;Uncomment to add your own bed temperature line + ;M109 S220 ;Uncomment to add your own temperature line + G21 ;metric values + G90 ;absolute positioning + ... + + :param filename: The filename of the file for which to retrieve the contents + :resheader Location: The statically served download location for the file of the format ``/downloads/files/`` + :statuscode 302: No error, regular redirect to statically served download location + +.. _sec-api-fileops-filecommand: + +Issue a file command +==================== + +.. http:post:: /api/files/(string:target)/(path:filename) + + Issue a file command to an existing file. Currently supported commands are: + + load + Selects a file for printing. Additional parameters are: + + * ``print``: Optional, if set to ``true`` the file will start printing directly after selection. + + **Example Request** + + .. sourcecode:: http + + POST /api/files/local/whistle_v2.gcode HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "load", + "print": true + } + + **Example Response** + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + {} + + :param target: The target location on which to delete the file, either ``local`` (for OctoPrint's ``uploads`` + folder) or ``sdcard`` for the printer's SD card (if available) + :param filename: The filename of the file for which to issue the command + :json string command: The command to issue for the file, currently only ``load`` is supported + :json boolean print: ``load`` command: Optional, whether to start printing the file directly after selection, + defaults to ``false``. + :statuscode 200: No error + :statuscode 400: If `target` is neither ``local`` nor ``sdcard``, the `command` is unknown or the request is + otherwise invalid + +.. _sec-api-fileops-delete: + +Delete file +=========== + +.. http:post:: /api/files/(string:target)/(path:filename) + + Delete the selected `filename` on the selected `target`. + + Returns a :ref:`Retrieve Response ` corresponding to the updated + file list after successful deletion. + + **Example Request** + + .. sourcecode:: http + + DELETE /api/files/local/whistle_v2.gcode HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + **Example Response** + + .. sourcecode:: http + + HTTP/1.1 200 Ok + Content-Type: application/json + + { + "files": [ + ... + ], + "free": "3.2GB" + } + + :param target: The target location on which to delete the file, either ``local`` (for OctoPrint's ``uploads`` + folder) or ``sdcard`` for the printer's SD card (if available) + :param filename: The filename of the file to delete + :statuscode 200: No error + :statuscode 400: If `target` is neither ``local`` nor ``sdcard`` or the request is otherwise invalid + :statuscode 403: If the file to be deleted is currently being printed .. _sec-api-fileops-datamodel: @@ -156,6 +386,33 @@ Retrieve response - String - The amount of disk space available in the local disk space (refers to OctoPrint's ``uploads`` folder) +.. _sec-api-fileops-datamodel-uploadresponse: + +Upload response +--------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``files`` + - 0..* + - Array of :ref:`File information items ` + - The list of files available in the system. Might be an empty list if no files are available + * - ``done`` + - 1 + - Boolean + - Whether the file is directly available for printing after receiving the response (``true``) or not, e.g. due + to first needing to be sliced into GCODE (``false``) + * - ``filename`` + - 1 + - String + - The name of the file that was just uploaded + .. _sec-api-fileops-datamodel-fileinfo: File information diff --git a/docs/api/general.rst b/docs/api/general.rst index 76a84ee8..af1c4644 100644 --- a/docs/api/general.rst +++ b/docs/api/general.rst @@ -10,19 +10,28 @@ Authorization ============= OctoPrint's API expects an API key to be supplied with each request. This API key can be either the globally -configured one (compare :ref:`fig-api-general-globalapikey`) or a user specific one if "Access Control" is enabled -(compare :ref:`fig-api-general-userapikey`). Users are able to generate and revoke their custom API key via the -"Change password" dialog (compare :ref:`fig-api-general-changepassword`). +configured one or a user specific one if "Access Control" is enabled. Users are able to generate and revoke their +custom API key via the "Change password" dialog. -The API key must be supplied as query parameter ``apikey`` to each request, e.g. +The API key must be supplied in the custom HTTP header ``X-Api-Key``, e.g. .. sourcecode:: http - GET /api/gcodefiles/local?apikey=abcdef HTTP/1.1 + GET /api/files HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + +If it is missing, OctoPrint will directly return a response with status :http:statuscode:`401`. If it is included in +the request but invalid, OctoPrint will directly return a response with status :http:statuscode:`403`. + +For testing purposes it is also possible to supply the API key via a query parameter ``apikey``, e.g. + +.. sourcecode:: http + + GET /api/files?apikey=abcdef... HTTP/1.1 Host: example.com -.. todo:: - Look into allowing to supply the API key as a custom ``Authorization`` scheme. +Please be advised that clients should use the header field variant if at all possible. .. _fig-api-general-globalapikey: .. figure:: ../images/settings-global-api-key.png @@ -45,3 +54,16 @@ The API key must be supplied as query parameter ``apikey`` to each request, e.g. The API key options in the "Change password" dialog. Users can generate and revoke their custom API key here. +.. _sec-api-general-contenttype: + +Content Type +============ + +If not otherwise stated OctoPrint's API expects request bodies and issues response bodies as ``Content-Type: application/json``. + +.. _sec-api-general-encoding: + +Encoding +======== + +OctoPrint uses UTF-8 as charset. \ No newline at end of file diff --git a/docs/api/index.rst b/docs/api/index.rst index 54b27f25..38412cad 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -8,4 +8,7 @@ API Documentation :maxdepth: 2 general.rst - fileops.rst \ No newline at end of file + fileops.rst + connection.rst + printer.rst + diff --git a/docs/api/printer.rst b/docs/api/printer.rst new file mode 100644 index 00000000..887e5e05 --- /dev/null +++ b/docs/api/printer.rst @@ -0,0 +1,147 @@ +.. _sec-api-printer: + +*************** +Printer Control +*************** + +.. _sec-api-printer-printhead: + +Issue a print head command +========================== + +.. http:post:: /api/control/printer/printhead + + Print head commands allow jogging and homing the print head in all three axes. Available commands are: + + jog + Jogs the print head (relatively) by a defined amount in one or more axes. Additional parameters are: + + * ``x``: Optional. Amount to jog print head on x axis, must be a valid number corresponding to the distance to travel in mm. + * ``y``: Optional. Amount to jog print head on y axis, must be a valid number corresponding to the distance to travel in mm. + * ``z``: Optional. Amount to jog print head on z axis, must be a valid number corresponding to the distance to travel in mm. + + home + Homes the print head in all of the given axes. Additional parameters are: + + * ``axes``: A list of axes which to home, valid values are one or more of ``x``, ``y``, ``z``. + + **Example Jog Request** + + Jog the print head by 10mm in X, -5mm in Y and 0.02mm in Z. + + .. sourcecode:: http + + POST /api/printer/printhead HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "jog", + "x": 10, + "y": -5, + "z": 0.02 + } + + **Example Home Request** + + Home the X and Y axes. + + .. sourcecode:: http + + POST /api/printer/printhead HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "home", + "axes": ["x", "y"] + } + + :json string command: The command to issue, either ``jog`` or ``home``. + :json number x: ``jog`` command: The amount to travel on the X axis in mm. + :json number y: ``jog`` command: The amount to travel on the Y axis in mm. + :json number z: ``jog`` command: The amount to travel on the Z axis in mm. + :json array axes: ``home`` command: The axes which to home, valid values are one or more of ``x``, ``y`` and ``z``. + :statuscode 200: No error + :statuscode 400: Invalid axis specified, invalid value for travel amount for a jog command or otherwise invalid + request. + +.. _sec-api-printer-hotend: + +Issue a heater command +====================== + +.. http:post:: /api/control/printer/heater + + Heater commands allow setting the temperature and temperature offsets for the printer's hotend and bed. Available + commands are: + + temp + Sets the given target temperature on the printer's hotend and/or bed. Additional parameters: + + * ``temps``: Target temperature(s) to set, allowed properties are: + + * ``hotend``: New target temperature of the printer's hotend in centigrade. + * ``bed``: New target temperature of the printer's bed in centigrade. + + offset + Sets the given temperature offset on the printer's hotend and/or bed. Additional parameters: + + * ``offsets``: Offset(s) to set, allowed properties are: + + * ``hotend``: New offset of the printer's hotend temperature in centigrade, max/min of +/-50°C. + * ``bed``: New offset of the printer's bed temperature in centigrade, max/min of +/-50°C. + + **Example Target Temperature Request** + + Set the printer's hotend target temperature to 220°C and the bed target temperature to 75°C. + + .. sourcecode:: http + + POST /api/control/printer/heater HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "temp", + "temps": { + "hotend": 220, + "bed": 75 + } + } + + **Example Offset Temperature Request** + + Set the offset for hotend temperatures to +10°C and for bed temperatures to -5°C. + + .. sourcecode:: http + + POST /api/control/printer/heater HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "offset", + "offsets": { + "hotend": 10, + "bed": -5 + } + } + + :json string command: The command to issue, either ``temp`` or ``offset`` + :json object temps: ``temp`` command: The target temperatures to set. Valid properties are ``hotend`` and ``bed`` + :json object offsets: ``offset`` command: The offset temperature to set. Valid properties are ``hotend`` and ``bed`` + :statuscode 200: No error + :statuscode 400: If ``temps`` or ``offsets`` contains a property other than ``hotend`` or ``bed``, the + target or offset temperature is not a valid number or outside of the supported range, or if the + request is otherwise invalid. + +.. _sec-api-printer-feeder: + +Feeder Control +============== + diff --git a/docs/conf.py b/docs/conf.py index 9476a8dd..36f4a5b2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -93,11 +93,17 @@ pygments_style = 'sphinx' # -- Options for HTML output --------------------------------------------------- -import sphinx_rtd_theme +# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +if not on_rtd: # only import and set the theme if we're building docs locally + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "sphinx_rtd_theme" +#html_theme = "sphinx_rtd_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -105,7 +111,7 @@ html_theme = "sphinx_rtd_theme" #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". diff --git a/docs/index.rst b/docs/index.rst index 0dab0952..5151535b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,9 +11,17 @@ This is a work in progress. The goal is to document OctoPrint's REST API, event allows different documentation per development branch in Git, which so far did not scale well with the Github-Wiki-based approach. -Contents: +Contents +======== .. toctree:: :maxdepth: 2 api/index.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` +* :ref:`http-routingtable` \ No newline at end of file