Requests and responses

Requests

A request is a call from a caller application to an endpoint to either query for data or initiate action.

Requests are made using URLs. Request URLs have the following components:

https://iap:8880/xc/rest/common/v1/activities/xc:207?fields=assignedGroup
\__________________/\______________________________/\___________________/ 
   application URL           endpoint path             query parameters

• Application URL - The URL to the InsuranceSuite application.
  • This value is required.
• Endpoint path - The path to the specific endpoint that the request is requesting.
  • This value is required.
  • Endpoint paths end either with a resource name (such as .../activities) or the ID of a specific element (such as .../activities/xc:207 in the example above). The ID of a specific element is also referred to as a path parameter.
• Query parameters - This is a set of query parameters that further defines the data that is desired in the response. For most endpoints, query parameters are optional.
  • For example, when you add ?fields=assignedGroup, you are specifying that the only field you want returned in the response is the assignedGroup field.
  • There are a small number of endpoints that require a query parameter. For example, to prevent resource-intensive calls, the Job API's /graph-schema endpoint requires a product parameter.

Some requests require a payload. The payload is a block of JSON-formatted text that contains information about one or more resources associated with the operation. Typically:

• GETs and DELETEs do not require request payloads.
  • For a GET, you only need to identify the resource you want information about, and this is done in the URL.
  • For a DELETE, you only need to identify the element to delete, and this is done in the URL.
• POSTs and PATCHes do require request payloads.
  • For a POST, you must specify data about the element to create.
  • For a PATCH, you must specify the data about the element that must be updated.

Responses

A response is the set of information returned by an API endpoint for a request to the caller application.

Some responses include a payload. The payload contains information about one or more resources that are returned by the operation. For example, for a request to get all open activities assigned to a given user, the response includes a payload with information about the open activities. For more information about the payload structure, see GETs.

The outcome of the operation is specified as an HTTP status code, also referred to as a response code. These codes are three-digit numbers. The general meanings of these codes are defined in the following table: