Some time ago, I posted the following on Social Media:
It was a version of what I’d been sharing for several years before that post. I think it is a helpful reminder to anyone working the Web API space.
In the intervening years, this has occasionally popped up in my feed along with a bit of commentary or questions. “What does this really mean?” “How does this actually work IRL?” “Is there a name for this thing?”
Yes, it has a name: Amundsen’s Maxim. The name surfaced a couple years back and kinda “stuck” — I’m ok with it.
But what does this really mean? I thought I’d poke around the generative AI world to see what at least one of the oracles of AI had to say.
Ask the Bard
Here’s what Google Bard had to say when I recently asked it about Amundsen’s Maxim (cleaned up a bit for this blog post):
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.
Handy Reference
That’s a decent write-up, actually. So, to create a handy reference, I’ve captured a version of the above text on a web page (http://amundsens-maxim.com) and will continue to collect resources and commentary as time goes on.
And, FWIW, I agree with the Bard:
“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.”
