REST API Design: Maintaining an API Style Guide

In a microservices architecture it is important to independently develop, run and deploy microservices.
However, it is beneficial for the services to be similar enough so that working on many services is seamless for developers.
That means similar deployment strategies, development frameworks and so on. This is why Starter Kits are so useful.
A common approach also makes work across teams much smoother.

An API style guide helps another dimension of this: API design consistency.

For example, suppose have a client library function which depends on a date field. It is much more re-usable across the company if we know all microservices should expose date fields in Unix epoch time with milliseconds or another standard format. When a new microservice is being integrated, we can quickly re-use this function with a new date field without having to figure our or potentially parse a new date format just for this service.

Of course, generally an API should follow good REST principles like well-defined resources and sub-resources, but the more we get into details the more can be spelled out and adopted as convention. Just how far REST principles themselves are taken can be an organization-wide convention.
Further, many details are independent of REST and fully up to the designer; this is where consistency across an organization really helps.

The API Style Guide could be a document on the internal API Developer Portal or other API hub, or simply a wiki or Confluence document.

The following elements are useful to document in an API Style Guide. This is not an exhaustive list.

Resource Naming

For example: use plurals with camel-case or plurals with dashes (e.g. /myResources or /my-resources)

Identifier Format

Example: Use UUID for all IDs or simply integers.
Include canonical IDs for all returned resources under the field “id”.

Date Formats

Example: Use Unix epoch time with milliseconds (or without milliseconds).

Date Field Naming and Human-Readable Versions

For example, always use the convention: “createdAt”, “modifiedAt”.
If these are in Epoch time, a human readable version could be “createdAtPretty”.
See this post for more details.

Slug Fields

Example: always provide a slug name or identifier for items.
See this post for more details.

Header Conventions

E.g.: Use headers named ‘Custom-Header’ or ‘X-Custom-Header’ (although this style is technically deprecated).

Content-type Headers

Always return the proper content-type header like “application/json”.

Controlling Response Format and Language

For example, use the Accept header to request specific data formats like JSON or XML. Another example: use the Accept-Language header to request responses in different languages like English and French.

Conventions for Descriptive Metadata for Lists

The style in which metadata about lists is returned along with list results is a key design decision.
Suppose for our resource /items we also want to know the number of items returned.

We can use a custom header:

Element-Count: 5

Or we can return a top level object and return the items as a field:

{
  "itemCount": 5,
  "items": [ ... ]
}

Such a design decision is very difficult to change once clients depend on the API and start requiring data about the list itself.
We can avoid API versioning and inconsistency by adopting a standard approach in a style guide across the company.

Documentation Approach

We can have a convention on documentation. For example, all services should expose documentation on /docs as OpenAPI (Swagger).

HTTP Status Codes

These should be consistent across most APIs, but we can write down some conventions. For example: a successful update request to a resource should respond with 204 No Content and no body.

Error Response Format

For example, all errors must be in a standard format like the sample below, including a documentation link:

{
  "code": "123",
  "message": "Error message",
  "link": "https://documentation-link"
}

Hypermedia Element Conventions

If services use any hypermedia elements, these could be standardized in the style guide.
For example, for linking to related resources we could specify using HAL links.

Again, this is definitely not an exhaustive list. Any aspect of microservice API design can be written down as a convention in an API Style Guide, making such a guide an asset for Developer Experience both for API developers as well as API consumers.