Skip to main content

API standards and conceptual flow

  • Updated

Asynchronous APIs are defined using the AsyncAPI 2.0.0 specification. This file is analogous to the OpenAPI specification. Synchronous APIs products use OpenAPI 3.0 for planning, documenting, and exposing their API. 

Conceptual flow for consuming APIs

Base URL

api.customer.britecore.com/*

JSON API

BriteCore services adhere to the JSON:API specification.

Note: Clients must use application/vnd.api+json for Content-Type and Accept headers.

Implementation

JSON:API types

JSON:API types are lowercase, singular, and hyphenated.

  • Best practice: "type": "policy"
  • Best practice: "type": "quote-revision"

JSON key case

JSON keys are in snake_case rather than camelCase or PascalCase.

  • Best practice: {"policy_number": "12345"}

Filtering

BriteCore implementations must accept one or more filtering key-value pairs from a request's query parameters.

Example: filter[key]=value&filter[key2]=value2

Pagination

Implementations adhere to the following:

  • first: the first page of data
  • last: the last page of data
  • prev: the previous page of data
  • next: the next page of data

In accordance with the JSON:API spec regarding pagination, the acceptable strategies are limited to page-based and cursor-based.

Metadata

Metadata isn't used at this time.

This restriction is in place until we can identify specific use cases that facilitate using metadata consistently among APIs.

Tools and libraries

Django Rest Framework JSON:API

URLs

BriteCore services use URLs that represent a resource, like a policy or a deliverable. Our URL standards include: 

Trailing Slash

A trailing slash / must be optional for all URLs.

Each URL must be accessible with and without a trailing slash.

The presence or absence of a trailing slash must not change the returned content.

A 301 or 302 response may not be used to make the trailing slash optional. This adds requests thus adding to the duration and expense of the request.

Examples

  • Best practice: /policies/ would be the URL to create a new policy or list policies.
  • Best practice: /policies/{id}/ would be the URL to retrieve, update, or delete a policy.
  • Best practice: /policies/{id}/payments/ would be the URL to create a new payment or list payments for a single policy.

URLs should begin with the service name

All URLs should begin with the name of the service without the "Brite" prefix.

For example, all API URLs from the BritePolicies service would be prefixed with /policies/.

  • Best practice: /policies/{id}/
  • Best practice: /policies/{id}/endorsements/
  • Best practice: /policies/endorsements/{id}/
  • Best practice: /policies/endorsements/{id}/contacts/
  • Best practice: /policies/contacts/{id}/
  • Avoid: /endorsements/{id}/
  • Avoid: /endorsement-contacts/{id}/

The exception to this rule is when developing multiple services in a single repository. This usually means the services will eventually be split out into separate repositories and the API should not change when that happens.

Shallow URLs

Since BriteCore typically uses UUIDs for our resource primary keys, prefer to keep URLs shallow.

  • Best practice: /lines/tables/{id}/ to identify a single Rate Table.
  • Avoid: /lines/{id}/risk-groups/{id}/tables/{id}/

This makes life easier for API callers, as they only have to pass in the ID for the resource they want rather the resource and all nested information about the resource (its Risk Group and its Risk Group's Line).

Plural resource names

Use the plural version of resource names rather than the singular version.

  • Best practice: /policies/{id}/payments/
  • Avoid: /policies/{id}/payment/

Hyphenated word separators

Use hyphens rather than underscores to separate words in a URL.

  • Best practice: /lines/rate-tables/{id}/
  • Avoid: /lines/rate_tables/{id}/
  • Avoid: /lines/ratetables/{id}/

Avoid HTTP methods/verbs in URLs

HTTP methods (and similar words like new, create, or update) are redundant when used in URLs. They shouldn't be used.

  • Best practice: POST to /policies/{id}/payments/ to create a payment.
  • Avoid: POST to /policies/{id}/payments/create/ to create a payment.

Validation errors 

If the incoming request data isn't valid, a 400 Bad request status should be returned. The errors returned appear in the following format:

{
    "errors": {
        "name": [
            {
                "message": "This field is required.",
                "code": "required"
            }
        ],
        "password": [
            {
                "message": "This field may not be blank.",
                "code": "blank"
            }
        ]
    }
}

Schema and documentation

Asynchronous APIs

Asynchronous APIs are documented in the AsyncAPI 2.0.0 specification.

This file is analogous to the OpenAPI specification.

Synchronous APIs

Services use OpenAPI 3.0 for planning, documenting, and exposing their API.

Operations

OpenAPI's Operation objects describe the operations performed by a path. SDK generators use them to determine the function names for each operation. The following standards apply for defining operations at BriteCore:

operationId key capitalization

Each Operation's operationId should be capitalized using camelCase rather than snake_case.

  • Best Practice: retrieveClaim
  • Best Practice: updateClaimant
  • Avoid: list_lines
  • Avoid: CreatePolicy

operationId format

For CRUD operations, the following prefixes should be used for the operationId:

  • get* for endpoints that retrieve a single resource.
    • Example: getClaim
  • list*s for endpoints that retrieve a list of resources.
    • Example: listClaims
  • create* for endpoints that create a single resource.
    • Example: createClaim
  • update* for endpoints that update a single resource.
    • Example: updateClaim
  • delete* for endpoints that delete a single resource.
    • Example: deleteClaim

For non-CRUD endpoints use an appropriate verb name, but always use the format {verb}{resource}.

Documentation rendering

The specification files are processed and rendered through the BriteAPI documentation service. 

Validation error format

All validation errors should contain a message and code. Validation errors can also contain a meta attribute. This allows the validation error to provide additional context surrounding the error.

API deployment

New API versions are introduced in a product version and installed via BriteDeploy, a service catalog. 

Versioning

  • Each API is versioned when it's directly or indirectly exposed to production.
  • Versions is specified in calver as YYYY.0M.0D.
  • Clients may specify the version in a custom header as X-BriteCore-Version.
  • Servers accept the version specified or return a 400 if the version is unsupported.
  • Servers return the version used to fulfill the request in the response header X-BriteCore-Version.
  • Servers use the latest version of the API if the request header X-BriteCore-Version is missing or no version is specified in the header.

Version lifecycle

  • Versions are classified as:
    • Current Version
    • Deprecated Version
    • Unsupported Version
  • Servers support a single Current Version.
  • Servers may support a single Deprecated Version.
  • The first published version of an API becomes its Current Version.
  • The Current Version may change in an observable way.
  • Changes to the Current Version are backward-compatible.
  • The Current Version becomes the Deprecated Version when a new Current Version is created.
  • The Deprecated Version must not change in an observable way.
  • The Deprecated Version becomes an Unsupported Version six months after its creation.
  • The Deprecated Version becomes an Unsupported Version when the Current Version is deprecated.
  • Servers return status code 400 to requests specifying an Unsupported Version.

Maintenance guidelines

  • APIs publish the first Current Version as soon as it's publicly exposed.
  • APIs don't publish a new Current Version before six months have passed since the previous publishing.
  • APIs may publish a new Current Version to remove undesired capabilities or interface quirks.
  • APIs shouldn't publish a new Current Version to perform non-critical cleanup.

Critical defects

  • A critical defect causes business disruption, unreasonable operational cost increase, or security issues.
  • Backward-incompatible changes to the Current Version are allowed to address critical defects.
  • Changes to the Deprecated Version are allowed to address critical defects.

Backward compatibility

Our standards include: 

  • Implement as tolerant readers.
  • Continue to accept and honor any previously supported payload shapes and contents.
  • Alter the returned payload shape or contents in any way that isn't entirely additive.
  • Change default observable behavior/side effects.

A change to an API version is considered backward-incompatible when given an unchanged dataset:

  • One or more data attributes are no longer exposed.
    • A field is removed from a served resource record.
    • An HTTP header is no longer set as part of a response.
  • One or more capabilities are no longer supported.
    • A resource endpoint is removed from the set of supported routes.
    • An HTTP verb is no longer supported for a resource endpoint.
    • A command endpoint is removed from the set of supported routes.
    • A value is no longer valid input for a parameter.
  • One or more required parameters are added to any endpoint.
    • A new or previously optional URL query-string parameter becomes required.
    • A new or previously optional HTTP request header becomes required.
    • A new or previously optional body parameter becomes required.
  • One or more observable side-effects change for any endpoint call.
    • A call becomes more expensive, but the upstream vendor's prices didn't change.
    • A call causes a different number of queryable resources to be deleted.
    • A call causes a different number of queryable resources to be created.
    • A call causes a different number of queryable resources to be updated.
  • One or more documented default behaviors change for any endpoint call.

Version Granularity

BriteCore's API is versioned per product. A product in BriteCore's API is delineated by the first segment of the URL (e.g., /claims/ or /quote/). A product may comprise any number of services, but this is transparent to the API consumer.

Internal HTTP APIs are versioned the same as the public HTTP APIs and only accessible by other BriteCore services.

Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles