An open admonishment to all API architects, designers, & implementors


"Remember, when designing your Web API, your data model is not your object model is not your resource model is not your message model." — Mike Amundsen



2016-08-21-maxim-tweet.png

The first public tweet of the maxim.

2016-11-apistrat-wadm-title.png

Web API Design Maturity Model — This talk (from 2016) contains one of the earliest public versions of the maxim.

What is Amundsen’s Maxim?

From Google Bard July 2023

Amundsen’s Maxim is a principle for designing RESTful APIs that was first proposed by Mike Amundsen in 2012. The maxim states that:

"Remember, when designing your Web API, your data model is not your object model is not your resource model is not your message model."

In other words, the different aspects of an API should be designed independently of each other. This allows for greater flexibility and scalability, as changes to one aspect of the API do not necessarily require changes to the others.

For example, the data model of an API defines the structure of the data that is exchanged between the client and the server. The object model, on the other hand, defines the way in which the data is represented in the code. The resource model defines the way in which the data is exposed to the client, and the message model defines the way in which the data is transported between the client and the server.

A Closer Look

Let’s take a closer look at each of these aspects of an API:

Data model

The data model defines the structure of the data that is exchanged between the client and the server. This includes the data types, the relationships between the data, and the constraints on the data.

Object model

The object model defines the way in which the data is represented in the code. This includes the classes, the methods, and the properties of the objects.

Resource model

The resource model defines the way in which the data is exposed to the client. This includes the URIs, the HTTP methods, and the representations of the resources.

Message model

The message model defines the way in which the data is transported between the client and the server. This includes the format of the messages, the encoding of the data, and the protocols that are used to transport the messages.

By designing these aspects of the API independently, it is possible to make changes to one aspect without affecting the others. This can make the API more flexible and scalable, as it is easier to add new features or change the way in which the data is represented.

For example, if the data model changes, the object model and the resource model do not need to change. This is because the data model is only concerned with the structure of the data, while the object model and the resource model are concerned with how the data is represented and exposed to the client.

Similarly, if the resource model changes, the data model and the message model do not need to change. This is because the resource model is only concerned with the way in which the data is exposed to the client, while the data model and the message model are concerned with the structure of the data and the way in which the data is transported between the client and the server.

Amundsen’s Maxim is a simple but important principle for designing RESTful APIs. By following this principle, you can create APIs that are more flexible, scalable, and maintainable.

Additional Benefits

Here are some additional benefits of following Amundsen’s Maxim:

It makes the API easier to understand

When the different aspects of the API are designed independently, it is easier for developers to understand how the API works.

It makes the API easier to test

When the different aspects of the API are designed independently, it is easier to test each aspect of the API separately.

It makes the API easier to maintain

When the different aspects of the API are designed independently, it is easier to make changes to the API without affecting the other aspects of the API.

If you are designing a RESTful API, follow Amundsen’s Maxim. It is a simple but important principle that can make your API more flexible, scalable, maintainable, and understandable.

Mike Amundsen

Author, Speaker, Advisor

An internationally known author and speaker, Mike Amundsen consults with organizations around the world on network architecture, Web development, and the intersection of technology and society. He works with companies large and small to help them capitalize on the opportunities APIs, Microservices, and Digital Transformation present for both consumers and the enterprise.

Amundsen has authored numerous books and papers. His latest book is "Web API Patterns and Practices Cookbook" (2022). Amundsen’s "Design and Build Great APIs" (2020) for Pragmatic Programmers Publishing is a popular developer-centric book. Amundsen also contributed to the O’Reilly Media book, "Continuous API Management" (2021,2018). His "RESTful Web Clients", was published by O’Reilly in February 2017 and he co-authored "Microservice Architecture" (June 2016). Amundsen’s 2013 collaboration with Leonard Richardson "RESTful Web APIs" and his 2011 book, “Building Hypermedia APIs with HTML5 and Node”, are common references for building adaptable Web applications.

Contacts