OpenAPI

This page provides the list of Seamless APIs and best practices for consuming them.

Best practices for consuming JSON APIs

This section describes best practices for consuming Seamless APIs that support the JSON:API specification. The list of JSON:API APIs are given below:

• Agency Configuration

• Compliance Service

• Document Service

• Finance Service

• Motor Registry

• Policy Management

• Pricing Engine

• Quotation Service

• Tenant Management

• User Management

All requests must be authenticated

Every request to Seamless APIs must be authenticated. For details of the authentication process, please see Authentication.

Use sparse fieldset selection

Clients should request only fields that they need from an endpoint. This practice is especially true for resource types that have a lot of fields or have fields with large data such as quotes in the Quotation Service and policies in the Policy Management. For example, the following request retrieves quotes with a sparse fieldset selection specified for the quotes resource. It also specifies the page size, page number, and a sort order.

If the client does not specify a sparse fieldset selection for a given resource type, the API may not include fields with large data for that resource type. This behaviour adheres to the specification.

If a client does not specify the set of fields for a given resource type, the server MAY send all fields, a subset of fields, or no fields for that resource type.

For more details of sparse fieldset specification, please refer to https://jsonapi.org/format/1.1/#fetching-sparse-fieldsets

Use paging

Requests for multiple resource instances should include a page size. If a page size is not specified, the default page size of 10 is used.

Do not use obsolete features

This section describes obsolete features that should not be used and may not be available in future updates to the APIs.

total-records

Responses for a multiple-resources request with pagination may include a total-records item in the meta property, which is the total of resource items match the query parameters. total-records is obsolete and may not be available in future updates of the APIs. Please use the new totalResources instead. For example, the following response include both total-records and totalResources, but again, totalResources should be used instead.

Filter syntax

JSON:API specification v1.1 doesn’t describe a standardized filter syntax. Therefore, the filter syntax varies and depends on the underlying technologies used to develop the APIs. For microservices in the list at the beginning of the Best practices for consuming JSON APIs section, the filter syntax is described in detailed at https://www.jsonapi.net/usage/reading/filtering.html. Please be informed of the following guidelines regarding to the filter syntax:

1. Legacy filters, e.g. ?filter[lastName]=eq:Smith are still supported, but they may be removed in a future update of the services. Any new code should use the new filter syntax, and existing code using legacy filters should be updated to use the new filters.

2. New filters MUST be prefixed with expr:, for example, ?filter=expr:equals(lastName,'Smith').

List of Seamless APIs