The REST API

The specific operation performed by the verbs depends on the resource being targeted. For more details, see REST resources.

Data Formats

When sending a resource (such as an event project or named constant) as part of a POST or PUT request, indicate the format by setting the HTTP Content-Type header on the request.

To indicate your preferred data format for response data (for all requests), indicate the format by setting the HTTP Accept header on the request. For clients without the ability to set HTTP headers, use the accept query parameter to indicate your preferred format, for example accept=application/json.

JSON schemas are provided for all resources in the Decision Server Events resources section; but application/xml is also supported for a number of resources. In these cases, the returned data contains the same information with the same overall structure, but in an XML format.

To understand resource representations in detail, you can create and deploy assets, such as events, actions, and event rules, by using the Decision Center console and Event Designer tools, then access the assets by using the REST API. These assets can then be used as the basis for requests to create new assets, or to update existing assets.

If you must issue a GET request that has a long query string, you might want to send a "virtual" GET instead. Specifically, a POST request with a Content-Type of application/x-www-form-urlencoded is treated as a GET request by the server, and the POST body is taken as the query string which is typically appended to the URI.

Response codes

For more detailed information about response codes, see REST API response codes and error messages. Individual resources reference topics might describe further error cases.

Globalization

The REST API treats the data in all resources as UTF-8 encoded data, and therefore supports the creation, modification, and reading of globalized assets.

Requests that cause server-side errors (for example, attempting to write an invalid event project to the event runtime) result in errors in the language of the server.

Locale-specific versions of the functions resource can be read by specifying the Content-Language HTTP header. The resulting resource representation is in the request language, if it is supported by Decision Server Events.

Query parameters

Several REST resources accept query parameters, that is parameters that are added to the end of the resource URI, to provide processing instructions to the server. The parameters supported by each resource are described in the resource reference, along with usage instructions, but come from the following set:

accept

An alternative way of indicating preferred data format for responses.

format

To indicate if a full or a summary data representation is to be returned from GET requests.

filter

To filter lists of resources; for example, when issuing a GET request to a resource addressed by group.

sortBy

To sort a list of resources.

attribs

To indicate which attributes are to be returned when reading a list of resources.

Also, the refresh parameter can be used with any resource to override the default refresh behavior of resources. Specifically, the parameter refresh=none can be sent, which indicates that any version of the resource being cached in the server code is to be returned, rather than, for example, the version of the resource being stored in the Decision Server Events database.

Use the refresh parameter with caution: for example, if there are no expected changes to the stored resources.

Last modified header

The HTTP Last-Modified header indicates when resources were last modified. Specifically, when reading event project and event runtime resources, the Last-Modified header indicates the last time an asset in the event runtime was modified.

The Last-Modified header is returned on every GET request, with a default value of the current time. Specific resource types such as event projects, the event runtime, assets, and the 12 asset types provide accurate Last-Modified values.

Compatibility with earlier versions

The REST API might change in the future. New versions of the API are accessed by providing a different revision number in the URI. Currently only one version of the API is supported: r1.