Join Keith Casey for an in-depth discussion in this video REST APIs: The six constraints, part 2, part of Designing RESTful APIs.
- [Instructor] In this video we'll talk about the final two constraints for a REST API. The fifth constraint is optional but probably the most powerful. It's the concept of Code on Demand. The concept is that when a client requests a resource, it also receives the code to act upon it. The real power is that the client doesn't have to know what is in the code, it just has to understand how to execute the code. The primary benefit is that the API can grow and extend itself without requiring the client applications to upgrade.
More importantly as new features and functionality become available, they are immediately available to the end user without requiring a browser upgrade. Code on demand isn't nearly as scary as it seems. Now let's cover the final and probably the most important constraint of all: Uniform Interfaces. There are four key principles that make up a Uniform Interface. First there's a concept of identifying our resources. Each resource should be uniquely addressable by a particular URL.
Generally there will be one and only one way to access this resource, but that is not a hard requirement. Think of the buildings on your street. They're also uniquely addressable. That's how they get mail. Next you need to be to manipulate or interact with those resources through those representations, through those URLs. Every interaction with a given resource should happen through the identifier we already gave it. It's worth noting that this isn't just adding an ID parameter at the end of the URL.
The final principle of uniform interfaces is called: Hypermedia As The Engine Of Application State. Also known as hate-e-os or hat-e-os, which is the worst name for a children's breakfast cereal ever. Before I tell you what it means in my own words, let's go to Wikipedia. In this case clients make state transitions only through actions that are dynamically identified within hypermedia by the server. Except for simple fixed entry points to the application, a client does not assume that any particular actions will be available for any particular resources beyond those described in the representations previously received from the server.
That's a mouthful. So what does it mean? It's actually relatively easy. Fundamentally it's a Choose Your Own Adventure book. If you've never read a Choose Your Own Adventure book, you don't read the pages in consecutive order: one, two, three, four. Instead your start on page and every time your character is faced with a choice you have the option to turn to one page for one choice and a different page for another choice and the pages you're allowed to go to are based entirely on the choices you have at that moment. This is hypermedia works.
At every point in the API, there are different things you can do with the API. And instead of having to go to the documentation to figure out what's available, each and every link is available within the API. So what does this look like in practice? Here's an example from the GitHub API. So we just hit the API just like we did before, api.github.com and now what we're going to see are a series of links. This is incredibly powerful. Notice that each of these URLs, let's look at the keys_url.
And this is the results from the GitHub API. Notice that each of the URLs has a specific named item that we can reference. Our client application doesn't have to remember how to create the user URL, it can simply ask the API for the URL that is based on this name. If you think about it, that's how humans work too. We don't remember what the logon URLs is for amazon.com. Instead we go to amazon.com and we skim the page until we see a button labeled: sign in, log in or something similar.
APIs can work exactly the same way. Also we don't have to memorize a link to get to the book section of the site. Again we visit the webpage and skim for a link labeled books. When our client applications don't have to remember the specific URLs for each and every action or link we want to visit, our clients can be simpler, kind of dumber and as a result, much more flexible. More importantly as your API adds additional functionality, you can just add it and our clients can update automatically.
And all this comes from the simple constraint of uniform interfaces.
- Approaches to adding an API
- Modeling tips
- Identifying activities and breaking them into steps
- Mapping activities to verbs and actions
- Creating and grouping API methods
- Validating your API
- HTTP headers and response codes
- Common design challenges
- Versioning best practices
- Hypermedia and documentation approaches