Overview |
Top Previous Next |
|
The HTTP API enables software to manage many server operations programmatically. Examples include updating location or output device records, or submitting files and sending them to output devices. With one exception, all requests require authentication to ensure only authorized access occurs. Most API requests can be accessed with either GET or POST HTTP `methods. Exceptions are when binary data must be uploaded, in which case the PUT method is used.
Requests Requests are via http or https requests, and all begin with a path "/api". For simplification of this documentation, all endpoints are documented assuming a prefix of a server URI composed of the protocol, hostname, and port of the server:
Following the server URI is a path. The combination of server URI and path is the endpoint.
Here is the one endpoint that does not require authentication: "/api/version". For example, to retrieve the version of the above server, you would use:
https://cp.example.com/api/version
This request returns four text lines, containing the server version, client version, serial number, and licensee name.
Each request has a specific endpoint and often additional parameters. The parameters are named values supplied in either GET or POST requests. Note that as with any http request, you must URL-encode the name=value pairs.
•Query string values in the URL, such as endpoint?field1=value1&field2=value%202 •Form POST values with the content type "application/x-www-form-urlencoded"
Responses Response formats vary by the endpoint and parameters. Status codes of 400-499 indicate structural or request-level errors, such as failed authentication or missing parameters. Check the response body for a detailed message. Status codes of 200-299 indicate the request succeeded, but you must check for error responses that start with the text "Error: message".
When a response is a JSON object, the Content-Type header will be "application/json".
The following sections discuss authentication and the various endpoints that are available. Note the following in these specifications:
•In endpoints, items in italics are to be replaced with values •In endpoints, items not in italics are to be used exactly as shown •Items in square brackets are optional, and the square brackets are not part of the syntax •Items separated by vertical bars (|) indicate a choice of options, one of which should be used •When parameters are specified with no data type, it is a string
|