Join Keith Casey for an in-depth discussion in this video Why good API design is important, part of Designing RESTful APIs.
- [Instructor] Welcome to Designing RESTful APIs. In this course, we'll talk through API design, what to consider, some things to exclude and design patterns that'll fit no matter what. But let's talk about your API. To set the tone for the rest of today, let's understand one important aspect. API design is hard. It's a game of trade-offs. But more than anything, we want to be deliberate about our choices because first, we have to decide what functionality we want to expose.
Then we have to determine how to expose it. Then you have to figure out the best ways to expose it. Then you have to adjust and improve as you figure out your assumptions and use cases who were wrong or just sometimes incomplete. Finally, as you learn about your customers and unexpected use cases, you have to rethink some things from the ground up. Overall, it touches on some of the hardest problems in computer science. The challenges at good API design involves naming things well while simultaneously describing how to interact with those things.
Even worse, as the API sees the real world, the goals and the purpose of the API will evolve. This may require us to find better words to describe our efforts and adjust accordingly, which gets a versioning and backwards compatibility. All this brings us to the first conceptual cover, affordances. In the simplest terms, an affordance is something which allows you to perform an action or accomplish a goal. For example, a doorknob is an affordance, which allows you to open a door.
A switch is an affordance for turning on and off a light. When you consider API design, everything you allow a user to do is an affordance. The potential risk is that we have three different aspects in play. First, we have what the API allows you to do. Second, we have what the API makes easy. Finally, we have what you want to do, the user, what do you want to accomplish? When these three things don't fit, we may have a useless API, or maybe a powerful API that doesn't do what we need.
But when all three of these are aligned, we have a unique combination that's incredibly powerful but so subtle you don't even notice. For example, let's talk about coffee cups. A coffee cup is a great thing. It's ideal at holding a hot beverage but they tend to get hot. Then along comes the amazing innovation of the handle. A handle is designed so you can hold a hot cup without burning your hand. But the great thing about a handle is that you can use it for hanging it on a hook.
In this case, we have a goal with a simple solution that allows other use cases without any additional effort for the user. Of course, while APIs can be useful and powerful to accomplish many things, adding them is not as simple as you think. So, let's talk about scenarios where you might need to add an API.
- 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