The Constellation DX API

It is important to note that there are two versions of the DX API:

• Constellation DX API
• Traditional DX API

The Constellation DX API focuses on View-based authoring. The Traditional DX API focuses on section-based authoring. 

Constellation DX API differs from Traditional DX API in several important ways:

• There is an entirely different JSON structure, which clearly separates data from the View layout.
• The number of API calls is reduced.
• New functionality has been added with additional endpoints. For example, there are endpoints for following or unfollowing a Case, and there are endpoints for changing Case Stages.
• Hypermedia is the Engine of Application State (HATEOAS). As a result, responses provide references to available actions.
• A prebuilt interpreter is included that is compatible with established frameworks, such as Angular, React, and Web Components.

Constellation DX API is centered around App Studio and React-based View authoring instead of harnesses and sections, and should only be used with Constellation Applications.

When making requests to the Constellation DX API, keep in mind that an API request is a message that a client sends to get data from a server. Each request can contain a method and path parameters, headers, query parameters, and a request body with fields that specific API endpoint requires.

Path parameters

Path parameters determine which Constellation DX API endpoint is accessed. This determines the response that is returned from the API call.

For example, the GET /assignments/{id}/actions/{actionID} path parameter is a request that returns details for a specific flow action for an assignment including information related to the View.

Headers

HTTP headers manage the connections between the client and the server. Headers consist of key-value pairs and are included in the HTTP message to convey metadata about the request. Constellation DX APIs use the following headers:

x-origin-channel 

The x-origin-channel header represents the origin of the request for example, web or mobile). This can be used to pick different circumstances of a Rule to allow different processing, based on the origin of the request. A common example is customizing the UI to scale automatically to fit different screen sizes and orientations if the request originates from a mobile device.

if-match and eTag 

The if-match and eTag are used in combination for optimistic locking, a strategy where multiple users have the ability to update a record.

The eTag header is included in DX API responses and represents the current pxSaveDateTime, which is a system property that represents the date and time when a particular instance (a Case, work item, or any other data object) was last saved in the system. 

When a user makes a request, the eTag header in the response represents the last time that resource was updated. In subsequent requests, the if-match header is included in the request with the value of the eTag from a previous request. Essentially this is a way of requesting to update a resource only if the resource has not been updated since the last request. This avoids multiple users inadvertently overwriting one another's changes.

In other words, when employing an optimistic locking strategy, a check is done when the assignment is submitted. When a resource is fetched from the service, an eTag value (pxSaveDateTime of the Case) is sent in the response header. When a user submits, the eTag value received in the previous response must be passed as the if-match request header. If this if-match matches the current pxSaveDateTime, only then is the user allowed to perform the update operation. If the if-match value does not match the current pxSaveDateTime the user receives an HTTP 409 Conflict error.

This if-match header is a mandatory header for all updates.

Of note, when employing a pessimistic locking strategy, if a Case is locked by a user, the system does not allow another user to open the Case and get the Assignment details. Instead, the system returns an HTTP 423 - resource locked error.

Query Parameters

Query parameters are a way to include additional information in a request's URL. Query parameters are appended to the end of a URL after a question mark (?), and are separated by ampersand symbols (&). The allowed query parameters are unique to each API endpoint. Common query parameters in Constellation DX API include viewType and pageName.

viewType query parameters specify how much UI metadata is returned, and support the following values:

• Page: the full page including all widgets
• Form: just the action area
• Fields: the form fields without any layout information
• None: only Case data is returned

The pageName query parameter specify the name of a View page that a DX API endpoint can access.

Request Body

Requests that use the POST, PUT, or PATCH method require a request body. The request body contains the information needed by the server to create or update the resource, including caseTypeID, parentCaseID, content, pageInstructions, and attachments.

• The caseTypeID element is required only during Case creation.
• The parentCaseID element is required only during Case creation.
• The content is a map representation (key-value pairs) of properties to be added or updated.
• The pageInstructions element is a list of page-related operations to be performed on embedded pages, page lists, or page group properties.
• The attachments element is a list of attachments.

In response to each client request to the API, the server sends back relevant data, which is called the response. Each API endpoint returns a unique JSON response. Though each response is unique, there are some shared properties across Constellation DX API responses.

In the JSON response, there are four important top level properties: data, uiResources, nextAssignmentInfo, and confirmationNote.

data

data contains Case details such as the status of the Case, available actions, SLA information, a list of available Stages, as well as information about users referenced in fields in the View, such as an Assignee or the Operator routing a Case.

uiResources 

uiResources contain UI meta-data needed to render a page or form.

nextAssignmentInfo

nextAssignmentInfo contains information about the next Assignment, such as the context and id. The nextAssignmentInfo property only appears in the response if another Assignment is configured after the current one.

confirmationNote 

confirmationNote is a note that is visible to the end users during Case processing. The confirmationNote property only appears in the last Stage of a Case.

To better secure the endpoints, Constellation DX API always uses OAuth 2.0 as the authentication type.

Check your knowledge with the following interaction: