From 09bed4e74fcf4a87b905d3411abc2c87dcbe7379 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Sun, 15 Dec 2013 18:45:38 +0100 Subject: [PATCH] Started documenting OctoPrint's REST API --- docs/api/fileops.rst | 264 ++++++++++++++++++++++++ docs/api/general.rst | 47 +++++ docs/api/index.rst | 11 + docs/conf.py | 9 +- docs/index.rst | 13 +- src/octoprint/server/ajax/gcodefiles.py | 14 +- 6 files changed, 338 insertions(+), 20 deletions(-) create mode 100644 docs/api/fileops.rst create mode 100644 docs/api/general.rst create mode 100644 docs/api/index.rst diff --git a/docs/api/fileops.rst b/docs/api/fileops.rst new file mode 100644 index 00000000..6d095b6b --- /dev/null +++ b/docs/api/fileops.rst @@ -0,0 +1,264 @@ +.. _sec-api-fileops: + +*************** +File operations +*************** + +.. _sec-api-fileops-retrieveall: + +Retrieve all files +================== + +.. http:get:: /api/gcodefiles + + Retrieve information regarding all GCODE files currently available and regarding the disk space still available + locally in the system. + + Returns a :ref:`Retrieve response `. + + **Example request**: + + .. sourcecode:: http + + GET /api/gcodefiles?apikey=abcdef HTTP/1.1 + Host: example.com + + **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" + "gcodeAnalysis": { + "estimatedPrintTime": "00:31:40", + "filament": "0.79m" + }, + "print": { + "failure": 4, + "success": 23, + "last": { + "date": "2013-11-18 18:00", + "success": true + } + } + }, + { + "name": "whistle_.gco", + "bytes": 0, + "size": "n/a", + "date": "n/a", + "origin": "sdcard" + } + ], + "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) + + Retrieve information regarding the GCODE files currently available on the selected `origin` and regarding the + disk space still available locally in the system. + + Returns a :ref:`Retrieve response `. + + **Example request**: + + .. sourcecode:: http + + GET /api/gcodefiles/local?apikey=abcdef HTTP/1.1 + Host: example.com + + **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" + "gcodeAnalysis": { + "estimatedPrintTime": "00:31:40", + "filament": "0.79m" + }, + "print": { + "failure": 4, + "success": 23, + "last": { + "date": "2013-11-18 18:00", + "success": true + } + } + } + ], + "free": "3.2GB" + } + + :param target: The target 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 + +.. _sec-api-fileops-datamodel: + +Datamodel +========= + +.. _sec-api-fileops-datamodel-retrieveresponse: + +Retrieve 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 requested files. Might be an empty list if no files are available + * - ``free`` + - 1 + - String + - The amount of disk space available in the local disk space (refers to OctoPrint's ``uploads`` folder) + +.. _sec-api-fileops-datamodel-fileinfo: + +File information +---------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``name`` + - 1 + - String + - The name of the file + * - ``bytes`` + - 1 + - Number + - The size of the file in bytes. Only available for ``local`` files, always ``0`` for files stored on ``sdcard``. + * - ``size`` + - 1 + - String + - The size of the file in a human readable format. Only available for ``local`` files, set to ``n/a`` for files + stored on ``sdcard``. + * - ``date`` + - 1 + - String representing a date and time in the format ``YYYY-MM-DD HH:mm`` + - The date and time this files was uploaded. Only available for ``local`` files, + set to ``n/a`` for files stored on ``sdcard``. + * - ``origin`` + - 0..1 + - String, either ``local`` or ``sdcard`` + - The origin of the file, ``local`` when stored in OctoPrint's ``uploads`` folder, ``sdcard`` when stored on the + printer's SD card (if available) + * - ``gcodeAnalysis`` + - 0..1 + - :ref:`GCODE analysis information ` + - Information from the analysis of the GCODE file, if available. + * - ``prints`` + - 0..1 + - :ref:`Print information ` + - Information regarding prints of this file, if available. + +.. todo:: + Make fields which are not available for ``sdcard`` (``bytes``, ``size``, ``date``) optional and don't include them + in the output if not available. Clients should be able to decide on their own what to display in such a case. + +.. _sec-api-fileops-datamodel-gcodeanalysis: + +GCODE analysis information +-------------------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``estimatedPrintTime`` + - 1 + - String representing a duration in the format ``HH:mm:ss`` + - The estimated print time of the file + * - ``filament`` + - 1 + - String + - The estimated usage of filament (length in meters and volume in cubic centimeters) in a human readable format. + Example: ``1.89m / 11.90cm³`` + + +.. _sec-api-fileops-datamodel-prints: + +Print information +----------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``failure`` + - 1 + - Number + - The number of failed prints on record for the file + * - ``success`` + - 1 + - Number + - The number of successful prints on record for the file + * - ``last`` + - 0..1 + - Object + - Information regarding the last print on record for the file + * - ``last.date`` + - 1 + - String representing a date and time in the format ``YYYY-MM-DD HH:mm`` + - Date and time when the file was printed last + * - ``last.success`` + - 1 + - Boolean + - Whether the last print on record was a success (``true``) or not (``false``) diff --git a/docs/api/general.rst b/docs/api/general.rst new file mode 100644 index 00000000..76a84ee8 --- /dev/null +++ b/docs/api/general.rst @@ -0,0 +1,47 @@ +.. _sec-api-general: + +******************* +General information +******************* + +.. _sec-api-general-authorization: + +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`). + +The API key must be supplied as query parameter ``apikey`` to each request, e.g. + +.. sourcecode:: http + + GET /api/gcodefiles/local?apikey=abcdef HTTP/1.1 + Host: example.com + +.. todo:: + Look into allowing to supply the API key as a custom ``Authorization`` scheme. + +.. _fig-api-general-globalapikey: +.. figure:: ../images/settings-global-api-key.png + :align: center + :alt: Global API key in the API settings + + The global API key can be found in the "API" settings + +.. _fig-api-general-userapikey: +.. figure:: ../images/settings-user-api-key.png + :align: center + :alt: User specific API key location in user list + + The user list in the "Access Control" settings shows the API key for users (if available) + +.. _fig-api-general-changepassword: +.. figure:: ../images/change-password-api-key.png + :align: center + :alt: API key options in "Change password" dialog + + The API key options in the "Change password" dialog. Users can generate and revoke their custom API key here. + diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 00000000..54b27f25 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,11 @@ +.. _sec-api: + +################# +API Documentation +################# + +.. toctree:: + :maxdepth: 2 + + general.rst + fileops.rst \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 7ed4a033..9476a8dd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,8 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.todo'] +extensions = ['sphinx.ext.todo', 'sphinxcontrib.httpdomain'] +todo_include_todos = True # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -92,9 +93,11 @@ pygments_style = 'sphinx' # -- Options for HTML output --------------------------------------------------- +import sphinx_rtd_theme + # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +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 @@ -102,7 +105,7 @@ html_theme = 'default' #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#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 8f99b1d6..c828f700 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,20 +3,13 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +##################################### Welcome to OctoPrint's documentation! -===================================== +##################################### Contents: .. toctree:: :maxdepth: 2 - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - + api/index.rst diff --git a/src/octoprint/server/ajax/gcodefiles.py b/src/octoprint/server/ajax/gcodefiles.py index ccc45988..a08f515b 100644 --- a/src/octoprint/server/ajax/gcodefiles.py +++ b/src/octoprint/server/ajax/gcodefiles.py @@ -23,16 +23,16 @@ def readGcodeFiles(): return jsonify(files=files, free=util.getFormattedSize(util.getFreeBytes(settings().getBaseFolder("uploads")))) -@ajax.route("/gcodefiles/", methods=["GET"]) -def readGcodeFilesForTarget(target): - if target not in [FileDestinations.LOCAL, FileDestinations.SDCARD]: - return make_response("Invalid target: %s" % target, 400) +@ajax.route("/gcodefiles/", methods=["GET"]) +def readGcodeFilesForTarget(origin): + if origin not in [FileDestinations.LOCAL, FileDestinations.SDCARD]: + return make_response("Invalid target: %s" % origin, 400) - return jsonify(files=_getFileList(target), free=util.getFormattedSize(util.getFreeBytes(settings().getBaseFolder("uploads")))) + return jsonify(files=_getFileList(origin), free=util.getFormattedSize(util.getFreeBytes(settings().getBaseFolder("uploads")))) -def _getFileList(target): - if target == FileDestinations.SDCARD: +def _getFileList(origin): + if origin == FileDestinations.SDCARD: sdFileList = printer.getSdFiles() files = []