What is an API Design System?

I have been involved in designing and building APIs for different organisations for the last ten years or more and one thing striking me is the importance of developer efficiency. Development of new products and ideas benefit a lot when developers have the right tools to build APIs.

An API design system enables us to create a coherent developer experience for our API consumers in an efficient way. It is our opinionated way of designing our APIs and a toolkit of components for efficient implementation of that design.

API design guidelines are not enough

API Design guidelines are documentation of how APIs we build should be designed. API Design guidelines are important as it makes it clear what an API should look like and what principles should be applied when designing APIs. Good API design guidelines are detailed and are carefully updated over time as new requirements and new knowledge emerge. But API design guidelines are far from enough to build APIs efficiently.

API design + Architecture + Components

To build good APIs in an efficient way we need a software architecture which supports our API design and components which fits that architecture.

Below is an example from an API design system I built, describing the flow of creating a new resource.

Example from an API Design System

API design guidelines which enables reuse

According to the API design guidelines of this design system (that I use as an example), creating a new resource is done with a POST to an URL where the path is the name of the resource type (e.g POST /orders to create an order).

The API design guidelines also states that endpoints should be designed for reuse by different applications and for different use cases (e.g POST /orders should be possible to use in mobile apps for customers as well as in integrations from partner CRM systems).

Architecture supporting the reusable design

One shared model per resource type

To enable reuse as described in the API design guidelines, the JSON data model for a specific resource type (e.g order) contains all properties (aka fields) of that resource type irrespective of API client (e.g partner CRM system or customer mobile app). This means every request property which is part of the resource type will be deserialized, even if it the request is forbidden according to the users permissions.

Authorization layer

Authorization is separated into its own layer. This layer is responsible for making sure only allowed requests will be processed and only allowed properties of the response will be returned to the client.

To reuse the same JSON data model for any client and to restrict access on property level are examples of architectural decisions which are made to support the API Design guidelines (of the example saying that API endpoints should be reusable for different use cases).

Implementation by configurable components

Deserialization of requests

The implementation to deserialize the JSON data model is done in a reusable component which converts a HTTP request to a JSON Object based on configuration provided in OpenAPI format (see OpenAPI parameter serialization and OpenAPI describing request body)

Authorization

The implementation of the authorization layer combines different reusable components. These components are responsible for user permissions in database, access control of requests and filtering of responses. All aspects of authorization are configurable in JSON and JSON Schemas and there is no need to write custom code to comply with the design guidelines.

Coherent developer experience by default

By reusing the exact same combination of components when creating new resources of any type (e.g cars, orders, or payments) we are able to provide a coherent experience for our API consumers.

Generic endpoint flow for creation of a resource with POST

The white boxes in the the picture above illustrate what differs in configuration between different kind of resources.

• JSON Deserialization/Serialization – data models are configured in OpenAPI format with JSON Schema. All relevant properties for each resource type irrespective of API client or user.
• Authorization of request – users permissions on field level. JSON Schema per permission (e.g one schema for “customer-permission” and another one for “partner-permission”)
• Authorization of response – filters the data user is not allowed to see. JSON Schema-filter per permission (e.g one schema-filter for “customer-permission” and another one for “partner-permission”)
• Persistence – which database and where in that database to store the created resource item.

Summary

• An API Design System can make API development more efficient.
• The API design must be supported by a software architecture and reusable components. An API design which is awesome as a document but hard to implement is inefficient and will cause frustration.
• An API Design System may enable development without coding and provide a coherent API experience for developers by default.
• In the API Design System I used as an example in this post – JSON, JSON Schema and OpenAPI are heavily used as they should be familiar to API designers and API developers of any programming language. This has proven to be successful and I would recommend you to check these standards out if you plan to work with APIs in any way.