The API Strategy Guide book is full of useful nuggets, go buy it! One of the nuggets I use to explain what REST is all about is in this book and it’s the subject of URIs which, to be fair, are the public face of your API so kinda key to get right (or the RESTafarians will be after you, queue Men At Work tune).
Sometimes the best way to describe what something is can be by starting by saying what it isn’t, and this is one of those somethings.
A REST API has Uniform Resource Identifiers (URIs) at its heart. These in conjunction with the HTTP verbs and responses make up the core of a REST API. But so many people get it wrong: why?
Before you read the following example, just consider these two points:
- REST is an architectural standard which means if you claim to follow it then you kinda have to follow the rules, but if you deviate for any reason that’s cool just be clear where and why you did, otherwise people will think you’re using the word REST like some marketing folks use the word CLOUD.
- REST is focused on resources, which is different from services. Check the AWS API which exposes services and doesn’t claim to be RESTful: the URIs look different.
With those two things in mind, let’s start with the wrong way before seeing the right way.
Wrong way to REST
The problem with the approach below is that the services/actions/verbs are coded into the URI along with the resources/nouns. Imagine a huge number of services and resources, and you can imagine a very large and complex URI namespace for consumers/clients to learn. Not RESTful.
This snippet is from the API Strategy Book (go buy it!)
The right way to REST
The whole point of REST, in my humble opinion, is to simplify things. And the Wrong Way example above is not simple at all. Focusing on exposing only resources in the URI makes the URI namespace simple and clean, and delegating the services and actions to HTTP verbs, query parameters and payloads makes for a simple interface. Simple means powerful and scalable. Here’s the snippet from the API Strategy Guide book:
Some REST principles
Of course you don’t have to follow this RESTful style, you can do whatever you want. But it’s pretty useful isn’t it? Follow a few constraints, set yourself free. Turns out there’s a few useful principles to keep in mind and the chaps that wrote the API Strategy Guide book get it down to a tee (go buy the book!)
- URIs matter
- Parameters matter
- Data format matters
- Return codes matter
- Abstraction matters (hide implementation complexity in headers, like version and auth)
- Versioning matters