Network System API

Table of Contents

• Introduction to the Qorus System APIs
• Qorus REST API
  • REST Client Time Zone Header
• Qorus REST API Versioning

Introduction to the Qorus System APIs

Qorus implements two network-available system APIs:

• REST API: the latest version of the Qorus REST API
  • REST API overview (newer, all new API development happens here)
  • Qorus REST API v8 (version-specific, latest version as of this release; Swagger schema)
  • Qorus REST API v7
  • Qorus REST API v6
  • Qorus REST API v5
  • Qorus REST API v4
  • Qorus REST API v3
  • Qorus REST API v2
  • Qorus REST API v1 (the original, base REST API)
  • Qorus Public REST API (no authentication required; Swagger schema)
  • Qorus REST API Data Structures
• Qorus RPC API (older, no new development)

Qorus REST API

The Qorus REST API has been implemented to use REST design principles for interfacing with Qorus Integration Engine.

The Qorus REST API follows the following REST design principles:

• GET requests never make changes (do not alter state)
• PUT requests can change server state and are also idempotent
• POST requests create new objects or configuration
• DELETE requests delete existing objects or configuration
• arguments are accepted in the URI or in the message body, however for all but simple requests it's recommended to send arguments in the message body

Qorus's REST API is designed to facilitate data exchanges between clients and the server. Serialized data is supported with the following Content-Types (clients indicate support by including these in the Accept header):

• text/x-yaml or application/x-yaml: YAML
• application/json: JSON
• text/xml: XML-RPC (for HTTP payload body encoding)
• text/html: HTML (for responses only)

The REST API is accessible from the Qorus HTTP server anchored at the path "/api"; the latest version of the REST API is accessible at "/api/latest"; see the following section for more information.

There are two methods of calling the API. Both methods are identical. Examples:

• PUT foo/bar action=myAction
• PUT foo/bar/myAction

Note

• If no Accept header is present, then it is assumed that the client accepts all media types; see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
• The qrest program provides the command-line interface to the Qorus REST API; note that qrest automatically adds the "/api/latest" URI path prefix to requests to Qorus.
• All future Qorus API development will be made with the REST API.

REST Client Time Zone Header

The following header can be given by clients to specify the client's time zone region:

• Qorus-Client-Time-Zone

For example:

Qorus-Client-Time-Zone: America/New_York

This allows the REST server to handle date/time values in the client's time zone.

Qorus REST API Versioning

The REST API is versioned in order to provide maximum backwards-compatibility to external applications and allow for maximum flexibility for future expansion.

Each REST API version besides the base version (version 1) is accessible with a URI prefix with its version name as follows:

• /api/v7: introduced in Qorus 6
• /api/v6: introduced in Qorus 5.1
• /api/v5: introduced in Qorus 5
• /api/v4: introduced in Qorus 4.1
• /api/v3: introduced in Qorus 4.0
• /api/v2: introduced in Qorus 3.1.1
• /api: (the original, base REST API)

The following URI prefix can be used to ensure that the latest version of the REST API is used at all times:

• /api/latest: this currently points to /api/v7