URIs

In the REST architectural style, URIs are used to indicate what object (resource) you want to access.

All API URIs must end with a slash ('/'). This is not some hard limitation, but other URIs are reserved for future extension. At the moment, if you attempt a request to a non-slash-terminated URI, you will receive an appropriate 30x redirect to the correct (slash-terminated) URI. Correctly configured clients (e.g. browsers) will follow the redirect. You shouldn't rely on this behavior though.

Each level of object model hierarchy that needs to be traversed corresponds to a URI component. As is standard procedure, all characters except alphanumerics ('A'..'Z', 'a'..'z', '0'..'9'), dashes ('-'), underscores ('_'), dots ('.') and tildes ('~') must be percent-encoded in URI components. Additionally, as a non-standard extension, URI components corresponding to hierarchy levels exactly equal to a single dot ('.') or two dots ('..') must be preceded by an exclamation mark (translated to '!.' or '!..', respectively) to avoid being eliminated by the dot segment removal procedure (see [1]). As literal exclamation marks are reserved and must be percent-encoded, this creates no ambiguity. The exclamation mark is otherwise reserved and should not be used non-escaped in any other case.

URI query parameters (like ?a=b&c=d ...) are not currently used, and reserved for future extension. It should be noted that some browsers that still survive despite all reason (IE 6) have problems with query parameters and digest authentication (see below).

Instead of query parameters, URI matrix parameters, a less-widespread feature, is used. They enable parallel operations on similar resources, and are discussed below. For now, it suffices to say that you should make sure that if you send characters ';', '=' or ',' in a URI path segment, you should percent-encode them unless you know what you are doing.

HTTP verbs

All verbs described in HTTP verbs are supported, with some Deviations from standards and common practices deviations from standard semantics.

HTTP authentication

In the REST architectural style, standard authentication methods are preferred. This includes Basic and Digest authentication.

Because Basic auth sends the username and password in plain text, it is disabled in newer DLI controllers unless "Allow legacy plaintext login methods" (/restapi/config/allow_plaintext_logins/) is set.

Digest auth is a challenge-response mechanism which is similar to the legacy authentication method in which the client received a challenge from the server and hashed it combined with the username and password to prove their identity, but has additional security features, as well as the benefits of being standard and widely implemented. Digest auth supports different "quality of protection" (qop) levels. qop="auth" and qop="auth-int" are supported. See the related RFCS [8], [7] for details.

If you are really security-conscious, you should disable HTTP completely in the controller's web UI, and use HTTPS only, as this will provide a higher degree of security and make Basic and Digest authentication methods more or less equivalent.

Input MIME types

Data in the following formats can be specified as a representation of a resource (for PUT or POST) using the Content-Type header:

application/json

JSON is the main interchange format. It is accepted by all resources in all circumstances. Other content types can be thought of as if they were reduced to it.

JSON data can be any valid JSON literals, not only objects; see RFC [3] for details. All REST API requests must supply valid credentials, and implicit CORS credentials passing is prohibited; this rules out different "JSON hijacking" attacks, should they ever become possible again.

text/plain

The plain text format is limited in what resources it can represent. It supports all scalar types (constant null is encoded as an empty string), and also arrays of scalar types (values are separated by commas ',').

If the resource is of a sum type, and there is an ambiguity (e.g. "false" could mean the constant false, or a string literal "false"), the request is ill-formed and denied.

If you face ambiguities, or need to express values of other types, you need to use JSON.

application/x-www-form-urlencoded

The URL-encoded format is limited in what resources it can represent. Scalar values are represented by a 'value' key with a value corresponding to the textual representation, if they have one. For example,

value=1

value=false

value=Hello

Field-based types can be represented in the format

 field1=value1&field2=value2&...

The values are again in textual representation.

If the resource is of a sum type, and there is an ambiguity (e.g. "false" could mean the constant false, or a string literal "false"), you may append $ to the field name to indicate that the value is to be interpreted as a string, or # to indicate that the value is to be interpreted specially (i.e. as a number, false, true, etc.; there's never an ambiguity between those); for example,

value#=1

indicates the number 1, while

value$=1

indicates the string "1". Likewise, in

field1#=value1&field2$=value2&...

field1 is assigned a non-string value, and field2 is assigned a string value.

Note that the $ and # characters need to be URL-encoded.

If you face ambiguities this simple convention can't resolve, or need to express values of other types, you need to use JSON.

Patch MIME types

Data in the following formats can be specified as a representation of a change to resource (for PATCH) using the Content-Type header:

application/json-patch+json

JSON patch is the main patch format. It is accepted by all resources in all circumstances. Other patch formats can be thought of as if they were reduced to it. See the RFC [4] for details and examples.

Note that paths in JSON patch documents are JSON pointers, as per the JSON patch RFC [5], and not URIs. They are normally either empty, or start with a slash (/), and never end with a slash. Their components are never percent-encoded (there are specific '~' escapes in JSON pointers [5]), and no matrix URI support is in place. Be sure not to confuse JSON pointers and relative URIs.

application/x-www-form-urlencoded

The URL-encoded format is limited in what resources it can represent. It is similar to the full resource representation, but must include only the values you want to change. The field names (or the 'value' keyword) may be preceded by 'new_' to emphasize that this is the new value you want to write. If you want to supply the previous value, and have it checked, you should prefix it with 'old_'. Note that in some cases, like changing the administrator username password, you may be forced to supply the old password value to be checked.

When such patches are handled, first all 'old_' values are checked against the resource values, and the patch is only applied if all of them match.

For example, the following patch:

old_name=admin&new_name=root&old_password=1234&new_password=4321

behaves as though you supplied the following JSON patch document instead:

[
 {"op":"test","path":"/name","value":"admin"},
 {"op":"test","path":"/password","value":"1234"},
 {"op":"replace","path":"/name","value":"root"},
 {"op":"replace","path":"/password","value":"4321"}
]

Requests to patch any objects with fields starting with old_ or new_ prefixes (currently no objects have such fields) are ill-formed. If you need to work with such objects, you need to supply the patch in the JSON patch format.

Output MIME types

Data in the following formats can be requested as a representation of a resource (usually for GET, but also other methods except DELETE) using the Accept header:

application/json

JSON is the main interchange format. It is retrievable for all resources in all circumstances. Objects which are not readable, or not reachable due to depth limitations, will be replaced to JSON references to them.

text/html

HTML is the browser output format, which enables you to interact with the API using the browser. Requests generated with the browser can serve as templates for your own requests, but you are by no means limited by them.

text/plain

Plain text is the simple human-readable format, not intended to be processed automatically. You should not rely on any particular format for it.

Preference indication

Some methods (e.g. PUT, PATCH and POST to create resources) can return a representation of the result, but it's optional. The HTTP Prefer header [10] can be used to indicate your preference. Requests with this header

 Prefer: return=representation

will return the representation of the created or modified resource, while requests with the header

 Prefer: return=minimal

will return only the status code and headers.

The server will respond with an appropriate Preference-Applied header if the preference has been understood and affected the output.