Linting guide

The API would become incompatible with existing consumers if the following changes were made:

• Removing or renaming APIs or API parameters or headers
• Removing or renaming response fields or headers
• Changes in behaviours for an existing API; including default parameter and argument behaviour
• Changes in casing of property names, at any point in the object graph (:warning: beware if assigning objects directly based on responses from other services)
• Changes in casing of headers (headers are defined as case-insensitive in the RFC, but many clients are case-sensitive)
• Changes in HTTP Status Codes
• Changes in error responses

See here for more information.

Detailed messages have the following format:

OpenAPI:

• action: specifies whether the change is a removal, update, or addition.
• code: describes what has been changed, such as path.remove.
• destinationSpecEntityDetails and sourceSpecEntityDetails: indicate a change in source and destination specifications.

AsyncAPI:

• action: specifies whether the change is a removal, update, or addition.
• path: indicate a change in source and destination specifications.

Minor versions of APIs need to be bumped and the changes documented, but major versions do not have to be released simultaneously. The examples of minor changes:

• Adding new API resources
• Adding new optional request parameters or headers to existing API methods
• Adding new properties or headers to existing API responses
• Changing the order of properties or headers in existing API responses
• Changing technology
• Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings

See here for more information.

We enforce conventions which the API title must follow. These requirements are:

• Must not include ‘API’
• Must not include ‘NewDay’
• Must not include version numbers (e.g. Customer V1 is not allowed)
• Must only have allowed characters (i.e. a-z A-Z () allowed)
• Must have a capitalized initial letter
• Must have spaces unless start with ‘New’ (indicates a brand)

See here for more information.

The version field in the spec must follow the format x.x. See here for more information.

The spec must contain a description field. Use this field to provide an overall description of the API what type of functionality it delivers.

The spec should contain a servers field, indicating the URLs from which the API can be accessed.

For each path in the spec, there must be an operationId specified.

For each path in the spec, there should be a description or summary field. The descriptions should be relevant to all operations in the path. summary is meant to provide a short summary and description is meant to be a longer description.

For each parameter in a given path, there should be a description field.

For each response in the spec, there should be an example populated with data that can be expected to be returned from the API. The example object should be in the content type (e.g. application/json) object for a given response.

For each response in the spec, there must be a description field. You can use the description to describe the conditions for an error response, for example.

For each response in the spec, there must be a 2xx and/or 500 response. The 2xx response should be the successful response and the 500 response should be the error response.

This warning will display if there are duplicate keys found in the spec file. e.g. x-pub-setting must only feature once in the spec page.

There must be a matching tag value in the spec for each of the categories defined in the tags file. See here for more information on current tags.

For each channel in the spec, there must be a description field. You can use the description to describe the purpose of the event.

For each property in the spec, there must be a description field. You can use the description to describe the purpose of the property.

We enforce conventions which all the URLs must follow. These requirements are:

• Must not include ‘api’ (e.g /account/123/cards instead of /api/account/123/cards)
• Must not include version numbers (e.g. /transactions instead of /v1/transactions)

See here for more information.

We enforce conventions which the schema name must follow. These requirements are:

• Must be UpperCamelCase
• Must be less than 32 characters

We enforce conventions which the fields and headers must follow. These requirements are:

• Fields must be lowerCamelCase
• Headers must be Capitalised-Kebab-Case
• x-Prefixed-Headers should be avoided

See here for more information.

The fields and headers descriptions must follow the conventions. These requirements are:

• Must start with a capital letter
• Must end with a full stop

Fields and headers should not contain the following words:

• context
• scope
• resource

Fields and headers naming should follow the convention.

To consult the list of standard fields and headers and fields and headers to be avoided, see here.

Fields and headers descriptions should follow the convention.

To consult the list of standard field and header descriptions, see here.

There is a requirement to provide an audit of user actions, ie who did a specific action within the New Day platform. You should use headers which match the standard claims used for JWTs:

• Sub
• Obo
• Channel

We also support the deprecated headers of the same name but with a context- prefix, like for many other headers. Note this prefix is lower case, in contrast to our naming conventions.