Skip to main content

API Standards (evolving)

Warning These standards are evolving and may all change at any point

Baseline API Standards for OPG teams to use when building new APIs.

Adopt these standards if there is no reason not to, but you may break any of them if you have a compelling need.

Infrastructure

Design

  1. Use JSON for request and response bodies
  2. Use lowerCamelCase for keys
  3. Prefer flat structure, we don’t have a standard response format and should keep things as minimal as possible (e.g. don’t use something like JSON:API, or have all responses like {"data": ...})

  4. Use RFC3339 to format dates

    Examples of RFC3339 formatted dates:

    • 2023-06-16
    • 2023-06-16T09:04:38Z
    • 09:04:46Z

Naming

REpresentational State Transfer (REST) is the defacto API architecture standard and the guidance below is on the assumption that REST will be used. The primary data representation in REST is a resource, which is a mapping to a set of entities. This dictates how REST APIs should be designed and the following princples should guide how the resources are addressed:

  1. Resources are represented by nouns. Resource names can be “real” nouns or abstract collections e.g. /users or /user-management.
  2. A resource can be a singleton or a collection. Collections are pluralised and singletons are addressed by ID. e.g. /users/1, where users is a collection and 1 is the singleton.
  3. Resources are hierarchical, with resources containing other resources. These relationships are denoted with forward slashes. e.g. /teams/1/users/2.
  4. A URI addresses the resource, not the action. HTTP methods should be used to indicate the action being performed. e.g. HTTP POST /users, not /users/create.
  5. Use query parameters to filter a resource collection instead of creating a new URI. e.g. /users?role=admin.
  6. Use hyphens to improve readability. Avoid underscores and other separators. e.g. /device-management/os-versions.
  7. Use lower case only. Case sensitivity is dependent on the browser, server, and host OS, so mixed-case should be avoided.
  8. Do not use file extensions in URIs. If this information needs to be communicated, use the Content-Type header.

Although we should strive to follow the standard as best practice wherever possible, there are situations where this isn’t possible, e.g. executing scripts via an API call. In these instances, it is necessary to provide adequate documentation so consumers are aware it is not addressing a resource.

Versioning

  1. Avoid versioning until there is a definite requirement
  2. Use SemVer to provide meaning and context to version changes
  3. Encode version in the header via Content Negotiation (Accept header) e.g. Accept: application/vnd.opg-data.v1+json
  4. Prefer additive changes over destructive ones
  5. Provide concrete deadlines and documentation to consumers
  6. Ensure APIs and network traffic is well-monitored

For further information, see the OPG Data versioning strategy

Documentation

  1. Use the OpenAPI Specification for documenting APIs
    • This may be used by your API’s consumers to automatically generate mocks using tools like Prism
  2. Store in the repo at /docs/openapi/openapi.yml

Authentication

  1. Use JSON Web Tokens (JWTs) to authenticate requests between OPG services
    1. Each JWT must contain the following claims:
      1. sub: Either an identifier of the user making the request (e.g. email address) or a service identifier if not user is involved
      2. iat: The timestamp of when the token was issued
      3. exp: The timestamp of when the token will expire
      4. iss: The service that issued the token
    2. APIs must validate “exp”, “iat” and “iss” claims, and the “nbf” claim if provided
  2. Where APIs only have consumers inside OPG, use infrastructure tools (e.g. AWS IAM) to restrict access to those services

Performance

  1. We have no departmental performance requirements, but you should discuss as a team if you can set any for yourselves.
  2. Monitor realtime performance of your production services with the tools provided by AWS, such as CloudWatch Metrics and X-Ray
  3. Consider alternative techniques for slow-running transactions such as using asynchronous request/response patterns, or queuing onerous processes to execute after the response has been sent
This page was last reviewed on 19 March 2024. It needs to be reviewed again on 19 September 2024 by the page owner #opg-developers .
This page was set to be reviewed before 19 September 2024 by the page owner #opg-developers. This might mean the content is out of date.