REST API Overview (Spider)

[Table of Contents](https://github.com/dell-oss/Doradus/wiki/Spider Databases: Table-of-Contents) | Previous | Next
Spider REST Commands: REST API Overview

---

The Doradus REST API is managed by an embedded Jetty server. All REST commands support XML and JSON messages for requests and/or responses as used by the command. By default, Doradus uses unsecured HTTP, but HTTP over TLS (HTTPS) can be configured, optionally with mandatory client authentication. See the Doradus Administration document for details on configuring TLS.

The REST API is accessible by virtually all programming languages and platforms. GET commands can also be entered by a browser, though a plug-in may be required to format JSON or XML results. The curl command-line tool is also useful for testing REST commands.

Unless otherwise specified, all REST commands are synchronous and block until they are complete. Object queries can use stateless paging for large result sets.

Common REST Headers

Most REST calls require extra HTTP headers. The most common headers used by Doradus are:

• Content-Type: Describes the MIME type of the input entity, optionally with a Charset parameter. The MIME types supported by Doradus are text/xml (the default) and application/json.

• Content-Length: Identifies the length of the input entity in bytes. The input entity cannot be longer than max_request_size, defined in the doradus.yaml file.

• Accept: Indicates the desired MIME type of an output (response) entity. If no Accept header is provided, it defaults to input entity’s MIME type, or text/xml if there is no input entity.

• Content-Encoding: Specifies that the input entity is compressed. Only Content-Encoding: gzip is supported.

• Accept-Encoding: Requests the output entity to be compressed. Only Accept-Encoding: gzip is supported. When Doradus compresses the output entity, the response includes the header Content-Encoding: gzip.

• X-API-Version: Requests a specific API version for the command. Currently, X-API-Version: 2 is supported.

• Authorization: This header is used to provide credentials when required, e.g., when Doradus is operating in multi-tenant mode and the command is directed to a specific tenant. Multi-tenant operation is described later.

Header names and values are case-insensitive.

Common REST URI Parameters

REST support the following general URI query parameters:

• format=[json|xml]: Requests the output message format in JSON or XML, overriding the Accept header if present.

• tenant={tenant}: Directs the request to the given tenant. This parameter is required for application REST commands when Doradus is operating in multi-tenant mode. The REST command is routed to specified {tenant}.

These parameters can be used together or independently. They can be added to any other parameters already used by the REST command, if any. Examples:

GET /_applications?format=json GET /_tasks?tenant=HelloKitty&api=2 GET /Msgs/Person/_query?q=LastName:Smith&s=5&tenant=HelloKitty&format=json

REST Commands in Multi-Tenant Mode

By default, Doradus executes in single-tenant mode, hence all applications are owned by a single default tenant. In this case, REST commands do not need the ?tenant parameter described in the previous section, and tenant credentials are not used. Even when Doradus is configured to operate in multi-tenant mode, REST commands intended for applications belonging to the default tenant omit the ?tenant parameter and authentication credentials. (The default tenant may be disabled in multi-tenant mode. See the Doradus Administration documentation for details.)

When Doradus is configured to operate in multi-tenant mode, REST commands intended for a specific tenant must include the ?tenant parameter. Each command must also include valid credentials for the corresponding tenant. Credentials are provided using basic authorization, which uses the general Authorization header format shown below:

Authorization: Basic xxx

Where xxx is the tenant user ID and password, separated by a colon, and base64-encoded. For example, if the user ID and password are Katniss:Everdeen, the header would look like this:

Authorization: Basic S2F0bmlzczpFdmVyZGVlbgo=

When Doradus receives this header, the base64 value is decoded and validated against the given tenant. Note that curl supports basic authentication by adding the “-u” parameter. Example:

curl -u Katniss:Everdeen http://localhost:1123/HelloKitty/...

If the tenant user ID or password is incorrect for the identified tenant, the REST command returns a 401 Unauthorized response.

The only commands that should not provide the ?tenant parameter in multi-tenant mode are system commands, which are not directed to a specific tenant. These commands are used by administrators to create tenants and perform diagnostic operations. In multi-tenant mode, system commands must use basic authorization and provide super user credentials. See the Doradus Administration documentation for details.

In the remainder of this documentation, all examples are displayed as if Doradus is operating in single-tenant mode or the command is intended for the default tenant in multi-tenant mode.

Common JSON Rules

In JSON, Boolean values can be text or JSON Boolean constants. In both cases, values are case-insensitive. The following two members are considered identical:

"AutoTables": "true"
"AutoTables": TRUE

Numeric values can be provided as text literals or numeric constants. The following two members are considered identical:

"Size": 70392
"Size": "70392"

Null or empty values can be provided using either the JSON keyword NULL (case-insensitive) or an empty string. For example:

"Occupation": null
"Occupation": ""

In JSON output messages, Doradus always quotes literal values, including Booleans and numbers. Null values are always represented by a pair of empty quotes.

Illegal Characters in XML Content

Although Doradus allows text fields to use all Unicode characters, XML does not allow element content to contain certain characters. The only characters allowed within XML content are in the following:

#x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

In an output message, when Doradus creates an XML element whose content would contain any characters outside of this set, it base64-encodes the entire element value and adds the attribute encoding="base64" to the element. For example, suppose a field value contains the Unicode value “ABC\u0000”. The 4th character, hex 0x00, is not valid in XML, hence the field value would be returned as follows:

<field name="foo" encoding="base64">QUJDAA==</field>

Similarly, in an input XML message, element content that contains invalid XML characters must be base64-encoded, and the application must add the encoding="base64" attribute to the corresponding element.

Common REST Responses

When the Doradus Server starts, it listens to its REST port and accepts commands right away. However, if the underlying Cassandra database cannot be contacted (e.g., it is still starting and not yet accepting commands), REST commands that use the database will return a 503 Service Unavailable response such as the following:

HTTP/1.1 503 Service Unavailable
Content-length: 43
Content-type: Text/plain

Database is not reachable. Waiting to retry`

When a REST command succeeds, a 200 OK or 201 Created response is typically returned. Whether the response includes a message entity depends on the command.

When a command fails due to user error, the response is usually 400 Bad Request or 404 Not Found. These responses usually include a plain text error message (similar to the 503 response shown above).

When a command fails due to a server error, the response is typically 500 Internal Server Error. The response includes a plain text message and may include a stack trace of the error.