Util

Test paths or URLs

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:

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 200 OK with a path test result when the test could be performed. The status code of the response does NOT reflect the test result!

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 200 OK with a URL test result 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.

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"]
}
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.

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"]
}
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.

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"
}
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.

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"
}
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.

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
}
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 Parameters:
 
  • command – The command to execute, currently either path or url
  • pathpath command only: the path to test
  • check_typepath command only: the type of path to test for, either file or dir
  • check_accesspath command only: a list of access permissions to check for
  • urlurl command only: the URL to test
  • statusurl command only: one or more expected status codes
  • methodurl command only: the HTTP method to use for the check
  • timeouturl command only: the timeout for the HTTP request
  • responseurl command only: whether to include response data and if so in what form
Status Codes:
  • 200 OK – No error occurred

Data model

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