MrDraw/docs/api/util.rst

.. _sec-api-util:

****
Util
****

.. _sec-api-util-test:

Test paths or URLs
==================

.. http:post:: /api/util/test

   Provides commands to test paths or URLs for correctness.

   Used by OctoPrint to validate paths or URLs that the user needs to enter in the
   settings.

   The following commands are supported at the moment:

   .. _sec-api-util-test-path:

   path
     Tests whether or provided path exists and optionally if it also is either a file
     or a directory and whether OctoPrint's user has read, write and/or execute permissions
     on it. Supported parameters are:

       * ``path``: The file system path to test. Mandatory.
       * ``check_type``: ``file`` or ``dir`` if the path should not only be checked for
         existence but also whether it is of the specified type. Optional.
       * ``check_access``: A list of any of ``r``, ``w`` and ``x``. If present it will also
         be checked if OctoPrint has read, write, execute permissions on the specified path.

     The ``path`` command returns a :http:statuscode:`200` with a :ref:`path test result <sec-api-util-datamodel-pathtestresult>`
     when the test could be performed. The status code of the response does NOT reflect the
     test result!

   .. _sec-api-util-test-url:

   url
     Tests whether a provided url responds. Request method and expected status codes can
     optionally be specified as well. Supported parameters are:

       * ``url``: The url to test. Mandatory.
       * ``method``: The request method to use for the test. Optional, defaults to ``HEAD``.
       * ``timeout``: A timeout for the request, in seconds. If no reply from the tested URL has been
         received within this time frame, the check will be considered a failure. Optional, defaults to 3 seconds.
       * ``status``: The status code(s) or named status range(s) to test for. Can be either a single
         value or a list of either HTTP status codes or any of the following named status ranges:

           * ``informational``: Status codes from 100 to 199
           * ``success``: Status codes from 200 to 299
           * ``redirection``: Status codes from 300 to 399
           * ``client_error``: Status codes from 400 to 499
           * ``server_error``: Status codes from 500 to 599
           * ``normal``: Status codes from 100 to 399
           * ``error``: Status codes from 400 to 599
           * ``any``: Any status code starting from 100

         The test will past the status code check if the status returned by the URL is within any of
         the specified ranges.
       * ``response``: If set to either ``true``, ``json`` or ``bytes``, the response body and the response headers
         from the URL check will be returned as part of the check result as well. ``json`` will attempt
         to parse the response as json and return the parsed result. ``true`` or ``bytes`` will base64 encode the body
         and return that.

     The ``url`` command returns :http:statuscode:`200` with a :ref:`URL test result <sec-api-util-datamodel-urltestresult>`
     when the test could be performed. The status code of the response does NOT reflect the
     test result!

   Requires admin rights.

   **Example 1**

   Test whether a path exists and is a file readable and executable by OctoPrint.

   .. sourcecode:: http

      POST /api/util/test HTTP/1.1
      Host: example.com
      X-Api-Key: abcdef...
      Content-Type: application/json

      {
        "command": "path",
        "path": "/some/path/to/a/file",
        "check_type": "file",
        "check_access": ["r", "x"]
      }

   .. sourcecode:: HTTP

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "path": "/some/path/to/a/file",
        "exists": true,
        "typeok": true,
        "access": true,
        "result": true
      }

   **Example 2**

   Test whether a path exists which doesn't exist.

   .. sourcecode:: http

      POST /api/util/test HTTP/1.1
      Host: example.com
      X-Api-Key: abcdef...
      Content-Type: application/json

      {
        "command": "path",
        "path": "/some/path/to/a/missing_file",
        "check_type": "file",
        "check_access": ["r", "x"]
      }

   .. sourcecode:: HTTP

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "path": "/some/path/to/a/missing_file",
        "exists": false,
        "typeok": false,
        "access": false,
        "result": false
      }

   **Example 3**

   Test whether a path exists and is a file which is a directory.

   .. sourcecode:: http

      POST /api/util/test HTTP/1.1
      Host: example.com
      X-Api-Key: abcdef...
      Content-Type: application/json

      {
        "command": "path",
        "path": "/some/path/to/a/folder",
        "check_type": "file"
      }

   .. sourcecode:: HTTP

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "path": "/some/path/to/a/folder",
        "exists": true,
        "typeok": false,
        "access": true,
        "result": false
      }

   **Example 4**

   Test whether a URL returns a normal status code for a HEAD request.

   .. sourcecode:: http

      POST /api/util/test HTTP/1.1
      Host: example.com
      X-Api-Key: abcdef...
      Content-Type: application/json

      {
        "command": "url",
        "url": "http://example.com/some/url"
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "url": "http://example.com/some/url",
        "status": 200,
        "result": true
      }

   **Example 5**

   Test whether a URL can be called at all via GET request, provide its raw body. Set a timeout of 1s.

   .. sourcecode:: http

      POST /api/util/test HTTP/1.1
      Host: example.com
      X-Api-Key: abcdef...
      Content-Type: application/json

      {
        "command": "url",
        "url": "http://example.com/some/url",
        "method": "GET",
        "timeout": 1.0,
        "status": "any",
        "response": true
      }

   .. sourcecode:: HTTP

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
        "url": "http://example.com/some/url",
        "status": 200,
        "result": true,
        "response": {
          "headers": {
            "content-type": "image/gif"
          },
          "content": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
        }
      }

   :json command:      The command to execute, currently either ``path`` or ``url``
   :json path:         ``path`` command only: the path to test
   :json check_type:   ``path`` command only: the type of path to test for, either ``file`` or ``dir``
   :json check_access: ``path`` command only: a list of access permissions to check for
   :json url:          ``url`` command only: the URL to test
   :json status:       ``url`` command only: one or more expected status codes
   :json method:       ``url`` command only: the HTTP method to use for the check
   :json timeout:      ``url`` command only: the timeout for the HTTP request
   :json response:     ``url`` command only: whether to include response data and if so in what form
   :statuscode 200:    No error occurred

.. _sec-api-util-datamodel:

Data model
==========

.. _sec-api-util-datamodel-pathtestresult:

.. list-table::
   :widths: 15 5 10 30
   :header-rows: 1

   * - Name
     - Multiplicity
     - Type
     - Description
   * - ``path``
     - 1
     - string
     - The path that was tested.
   * - ``exists``
     - 1
     - bool
     - ``true`` if the path exists, ``false`` otherwise.
   * - ``typeok``
     - 1
     - bool
     - ``true`` if a type check was not requested or it passed, ``false`` otherwise
   * - ``access``
     - 1
     - bool
     - ``true`` if a permission check was not requested or it passed, ``false`` otherwise
   * - ``result``
     - 1
     - bool
     - ``true`` if the overall check passed, ``false`` otherwise

.. _sec-api-util-datamodel-urltestresult:

.. list-table::
   :widths: 15 5 10 30
   :header-rows: 1

   * - Name
     - Multiplicity
     - Type
     - Description
   * - ``url``
     - 1
     - string
     - The URL that was tested.
   * - ``status``
     - 1
     - int
     - The status code returned by the URL, 0 in case of a timeout.
   * - ``result``
     - 1
     - bool
     - ``true`` if the check passed.
   * - ``response``
     - 0..1
     - string or object
     - If ``response`` in the request was set to ``bytes``: The base64 encoded body of the checked URL's response.
       If ``response`` in the request was set to ``json``: The json decoded body of the checked URL's response.
       Not present if ``response`` in the request was not set.
   * - ``headers``
     - 0..1
     - object
     - A dictionary with all headers of the checked URL's response. Only present if ``response`` in the
       request was set.