pingu_98/MrDraw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Started documenting OctoPrint's REST API

Browse source
This commit is contained in:
Gina Häußge 2013-12-15 18:45:38 +01:00
parent 7a8e71b837
commit 09bed4e74f
6 changed files with 338 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

264
docs/api/fileops.rst Normal file
View file

@ -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 <sec-api-fileops-datamodel-retrieveresponse>`.
**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 <sec-api-general-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 <sec-api-fileops-datamodel-retrieveresponse>`.
**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 <sec-api-general-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 <sec-api-fileops-datamodel-fileinfo>`
- 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 <sec-api-fileops-datamodel-gcodeanalysis>`
- Information from the analysis of the GCODE file, if available.
* - ``prints``
- 0..1
- :ref:`Print information <sec-api-fileops-datamodel-prints>`
- 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``)

47
docs/api/general.rst Normal file
View file

@ -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.

11
docs/api/index.rst Normal file
View file

@ -0,0 +1,11 @@
.. _sec-api:
#################
API Documentation
#################
.. toctree::
:maxdepth: 2
general.rst
fileops.rst

9
docs/conf.py
View file

@ -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
# "<project> v<release> documentation".

13
docs/index.rst
View file

@ -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

14
src/octoprint/server/ajax/gcodefiles.py
View file

@ -23,16 +23,16 @@ def readGcodeFiles():
return jsonify(files=files, free=util.getFormattedSize(util.getFreeBytes(settings().getBaseFolder("uploads"))))
@ajax.route("/gcodefiles/<string:target>", methods=["GET"])
def readGcodeFilesForTarget(target):
if target not in [FileDestinations.LOCAL, FileDestinations.SDCARD]:
return make_response("Invalid target: %s" % target, 400)
@ajax.route("/gcodefiles/<string:origin>", 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 = []