Util
Various tests
- 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
ordir
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 ofr
,w
andx
. If present it will also be checked if OctoPrint has read, write, execute permissions on the specified path.allow_create_dir
: Ifcheck_type
is provided and set todir
, this will allow OctoPrint to create the targetpath
as a directory if it doesn’t yet exist to allow for further tests.check_writable_dir
: Ifcheck_type
is provided and set todir
, this will check that the providedpath
is a writable directory. OctoPrint not only check if the permissions on the directory allow for writing but also attempt to write (and delete) a small test file.testballoon.txt
to the directory to test if writing is actually possible.
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 toHEAD
.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.validSsl
: Whether to validate the SSL connection if theurl
happens to be an HTTPS URL or not. Optional, defaults toTrue
.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 199success
: Status codes from 200 to 299redirection
: Status codes from 300 to 399client_error
: Status codes from 400 to 499server_error
: Status codes from 500 to 599normal
: Status codes from 100 to 399error
: Status codes from 400 to 599any
: 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 eithertrue
,json
orbytes
, 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
orbytes
will base64 encode the body and return that.content_type_whitelist
: Optional array of supported content types. If set and the URL returns a content type not included in this list, the test will fail. E.g.["image/*", "text/plain"]
.content_type_blacklist
: Optional array of unsupported content types. If set and the URL returns a content type included in this list, the test will fail. E.g.["video/*"]
. Can be used together withcontent_type_whitelist
to further limit broader content type definition, e.g. by puttingimage/*
into the whitelist, but disallowing PNG by includingimage/png
on the blacklist.
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!
- server
Tests whether a provided server identified by host and port can be reached. Protocol can optionally be specified as well. Supported parameters are:
host
: The host to test. IP or host name. Mandatory.port
: The port to test. Integer. Mandatory.protocol
: The protocol to test with.tcp
orudp
. Optional, defaults totcp
.timeout
: A timeout for the test, in seconds. If no successful connection to the server could be established within this time frame, the check will be considered a failure. Optional, defaults to 3.05 seconds.
The
server
command returns 200 OK with a Server test result when the test could be performed. The status code of the response does NOT reflect the test result!- resolution
Tests whether a provided hostname can be resolved (via DNS lookup). Supported parameters are:
name
: The host name to test. Mandatory.
The
resolution
command returns 200 OK with a Resolution test result when the test could be performed. The status code of the response does NOT reflect the test result!- address
Tests whether a provided address (or, if none is provided, the client’s remote address) is a LAN address and if so returns the subnet specifier in CIDR format.
address
: the address to test. If not set, the client’s remote address will be used
The
address
command return 200 OK with a Address test result when the test could be performed. The status code of the response does NOT reflect the test result!
Requires the
ADMIN
permission.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" } }
Example 6
Test whether a server is reachable on a given port via TCP.
POST /api/util/test HTTP/1.1 Host: example.com X-Api-Key: abcdef... Content-Type: application/json { "command": "server", "host": "8.8.8.8", "port": 53 }
HTTP/1.1 200 OK Content-Type: application/json { "host": "8.8.8.8", "port": 53, "protocol": "tcp", "result": true }
Example 7
Test whether a host name can be resolved successfully.
POST /api/util/test HTTP/1.1 Host: example.com X-Api-Key: abcdef... Content-Type: application/json { "command": "resolution", "name": "octoprint" }
HTTP/1.1 200 OK Content-Type: application/json { "name": "octoprint.org", "result": true }
Example 8
Test whether the client’s address is a LAN address.
POST /api/util/test HTTP/1.1 Host: example.com X-Api-Key: abcdef... Content-Type: application/json { "command": "address" }
HTTP/1.1 200 OK Content-Type: application/json { "address": "192.168.1.3", "is_lan_address": true, "subnet": "192.168.0.0/16" }
Example 9
Test whether
8.8.8.8
is a LAN address.POST /api/util/test HTTP/1.1 Host: example.com X-Api-Key: abcdef... Content-Type: application/json { "command": "address", "address": "8.8.8.8" }
HTTP/1.1 200 OK Content-Type: application/json { "address": "8.8.8.8", "is_lan_address": false }
- JSON Parameters
command – The command to execute, currently either
path
orurl
path –
path
command only: the path to testcheck_type –
path
command only: the type of path to test for, eitherfile
ordir
check_access –
path
command only: a list of access permissions to check forallow_create_dir –
path
command andchecktype
ofdir
only: whether to allow creation of the directory if it doesn’t yet exist (true
) or not (false
, default)check_writable_dir –
path
command andchecktype
ofdir
only: whether to test if the directory is writable by also trying to create a test file in it (true
) or not (false
, default)url –
url
command only: the URL to teststatus –
url
command only: one or more expected status codesmethod –
url
command only: the HTTP method to use for the checktimeout –
url
andserver
commands only: the timeout for the test requestresponse –
url
command only: whether to include response data and if so in what formhost –
server
command only: the server to testport –
server
command only: the port to testprotocol –
server
command only: the protocol to testname –
resolution
command only: the host name to testaddress –
address
command only: the address to test
- Status Codes
200 OK – No error occurred
Data model
Path test result
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
string |
The path that was tested. |
|
1 |
bool |
|
|
1 |
bool |
|
|
1 |
bool |
|
|
1 |
bool |
|
URL test result
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
string |
The URL that was tested. |
|
1 |
int |
The status code returned by the URL, 0 in case of a timeout. |
|
1 |
bool |
|
|
0..1 |
string or object |
If |
|
0..1 |
object |
A dictionary with all headers of the checked URL’s response. Only present if |
Server test result
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
string |
The host that was tested. |
|
1 |
int |
The port that was tested |
|
1 |
string |
The protocol that was tested, |
|
1 |
bool |
|
Resolution test result
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
string |
The host name that was tested. |
|
1 |
bool |
|
Address test result
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
string |
The address that was tested. |
|
1 |
bool |
|
|
0..1 |
string |
The detected subnet, if address is a LAN address. |