REST API for Decision Optimization Center

Presents the Decision Optimization Center REST API.

ETag management

When the API indicates that a resource is entity tagged (ETag response-header field provided), the response of the specified method contains an ETag field containing a generated ETag.

Whenever an ETagged resource is accessed with a request containing an ETag, the response can be 304 Not Modified if the resource did not change.

Range management

When the API indicates that it supports partial content with range, a "range" header can be specified in the request to limit the number of items returned in a list. The header format must be as follows:

Range: items = <start> - <end>

<start> and <end> must be strictly positive numbers to specify the desired range of items, <start> and <end> are inclusive.

Then, the response will contain only the requested elements with the HTTP status code of 206 and header "Content-range" as follows: Content-range : items <start>-<end>/<size>

<size> is the size of the full list.

If the range header does not have the type "items" or cannot be parsed it is ignored and the full list is returned.

If the requested <end> is greater than the actual size, it is treated as the last possible index of the list.

If the range is empty, i.e. end == start-1, an empty list is returned even if the range is invalid.

If the range header specifies an invalid range, HTTP error 416 is returned.

Method responses

Unless stated otherwise, the REST API for Decision Optimization Center returns the following responses:

  • The GET method returns <code>200 OK</code> and the resulting entity is encoded in the response (see individual response documentation).
  • The POST method returns <code>201 Created</code> and return the URI of the created resource.

  • The PUT method returns <code>204 No Content</code>.

  • The DELETE method, when used on unique and single resources, returns <code>200 OK</code> with a deleteStatus encoded in the response. The deleteStatus states whether the delete operation succeeded (status is DELETED) or could not be performed (status is NOT_FOUND).

  • The DELETE method, when used on set of resources, returns <code>204 No Content</code>.

Exception management

When the server returns with an error code (any of the 400 range or 500 range codes), the response may contain a body to give more information about the error. The content format will be JSON or XML following the specified "Accept" header. Also, a custom header 'X-Exception' is returned to indicate that such a content can be parsed in the response.