Endpoints

Every endpoint has a root resource. The root resource is the resource which the endpoint creates, updates, deletes, or queries for. Every call to an endpoint makes use of the root resource.

For example, the root resource for the /common/v1/activities endpoint is Activity. This endpoint is used to potentially create, update, delete, or queries for activities.

Most endpoints also include child resources. A child resource is a resource related to the root resource. Child resources improve the usability of an endpoint by providing access to information related to the root resource. For example, the /common/v1/activities endpoint has one child resource - Notes. This means you could use the endpoint to:

• Query for a specific activity (and only the activity)
• Query for a specific activity and its related notes

Every call to an endpoint must make use of the root resource. The use of child resources is optional.

Inline and included resources

Child resources can be declared either as inline resources or included resources.

• An inline resource is a resource that appears in the attributes section of the payload inline with the other root resource fields, such as an Activity resource's assignedUser field. These resources may be included in a response by default and can be controlled through the fields query parameters.
• An included resource is a resource that appears in the included section at the bottom of the payload, such as an Activity resource's Notes. These resources are not included in a response by default and must be controlled through the included query parameters.

For more information on inline and included resources, see GETs.

A method is a type of action a caller application can take on a resource through an endpoint. Methods are also referred to as verbs or operations. Cloud API supports the following subset of HTTP methods:

• GET - Used to request resources.
• POST - Used to create resources. Also used to execute business actions, such as quoting a submission or submitting a claim.
• PATCH - Used to update resources.
• DELETE - Used to delete resources.

Every endpoint supports one or more of these methods. For example, in the Common API:

• The notes/{noteId} endpoint supports GET, PATCH, and DELETE.
• The /activities endpoint supports only the GET operation.

The HTTP methods are designed for CRUD operations (Create, Read, Update, Delete). Some business processes in InsuranceSuite applications are available to Cloud API but do not readily map to any of these operations, such as assigning objects, closing objects, or approving objects. As a general rule, the custom actions that trigger these processes use the POST method.

Method mapping to elements and collections

In general:

• You can GET either an element or a collection.
• You POST a collection to create an element.
• You POST to a custom action (to execute a business action).
• You PATCH an element.
• You DELETE an element.

For example:

Method	On endpoint...	Does the following...
GET	/activities	Returns all activities assigned to the current user
GET	/activities/{activityId}	Returns the details for the specified activity
POST	/activities/{activityId}/notes	Adds a new note to the specified activity
POST	/activities/{activityId}/assign	Assigns the activity
PATCH	/activities/{activityId}	Updates information on the specified activity
DELETE	/notes/{NoteId}	Deletes the specified note

Contrasting endpoints and methods

Technically speaking, when an endpoint supports multiple methods, it is still a single endpoint. However, in casual discussion, each method is sometimes referred to as a separate endpoint. For example, consider the following:

• GET /common/v1/activities
• POST /common/v1/activities

This is a single endpoint (/common/v1/activities) that supports two methods (GET and POST). However, in a casual sense, it is sometimes referred to as two endpoints (the GET /activities endpoint and the POST /activities endpoint).

The PUT method

Within REST API architecture, there are two methods that modify existing resources - PATCH and PUT. PATCH is used to modify a portion of an existing resource (while leaving other aspects of it unmodified). PUT is used to replace the entire contents of an existing resource with new data. Cloud API supports the PATCH operation, but not the PUT operation. This is because nearly every method that modifies an InsuranceSuite object modifies only a portion of it while keeping the rest of the object untouched. This behavior maps to PATCH, but not to PUT.

Every endpoint has a path. The path is the portion of the URL used by caller applications to identify the specific endpoint.

For Cloud API, every path consist of the following pattern:

rest/<APIname>/<APImajorVersion>/<endpointName>

For example, consider the path: rest/common/v1/activities:

• common is the name of the API to which the endpoint belongs.
• v1 is the major version number of the API
• activities is the endpoint name

The major version number provides information about the backwards compatibility of the endpoint. For more information, see Version numbers for major and minor releases.

A path can also contain a reference to a specific resource. For example, the path /activities/xc:20/notes refers to the notes for activity xc:20. When a path includes a reference to a specific resource, the generic path name is specified using {typeId}, where type is the resource type. For example, the generic path for /activities/xc:20/notes is /activities/{activityID}/notes. A reference to a specific resource in a path is known as a path parameter.

For most endpoints, the endpoint name is the same as the resource name, with the following conventions and caveats:

• If the endpoint's root resource is an element, the endpoint name ends in a singular noun (such as /activity) or a resource reference (such as /activity/{activityId}).
• If the endpoint's root resource is a collection, the endpoint name ends in a plural noun (such as /activities).
• If the endpoint executes a business action, the endpoint name ends in a verb (such as /{activityId}/assign).
• The endpoint name is often close to, but not identical to, the resource name.
  • Endpoint names use lower case, whereas resource names use mixed case (for example, the root resource for the /activity endpoint is Activity)
  • Endpoint names use hyphens to separate words, whereas resource names do not (for example, the root resource for the /accounts/{accountId}/activity-patterns endpoint is ActivityPattern)
  • In some cases, the endpoint name may differ from the root resource name (for example, the root resource for the /accounts/{accountId}/contacts endpoint is AccountContact)