Join Keith Casey for an in-depth discussion in this video Three approaches to adding an API, part of Designing RESTful APIs (2014).
In this video we're going to talk about three strategies for creating an API. To set the tone of the rest of today, let's understand one important aspect. API design is hard. It's a game of trade-offs. First you have to decide what sort of functionality you want to expose. Then you 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 your figure out your assumptions and use case were wrong or just incomplete. Overall, it touches on some of the hardest problems in computer science.
The challenge is that good API design involves naming things correctly, accurately and completely, 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 will require us to find better words to describe our efforts and adjust accordingly. We'll talk about it more later on, but caching is an entire subject that we could spend hours talking strategy and tactics. In this course we'll cover one common strategy. Which brings us to the first concept we'll cover. Affordances. In the simplest terms, an affordance is something which allows you to perform an action or accomplish a goal.
For example, a door knob 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, the user, wants to accomplish. When those three things are misaligned, we may have a useless API, or maybe a powerful API that doesn't do what we need.
When all three are aligned, we have a unique combination. 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 to hold a hot cup without burning your hand. Sure enough, the handle is an easy and simple way to hold a cup. Finally, while a user might want to just hold a hot cup, they may want to accomplish other things, like hanging the mug. Sure enough, the handle works for that too. Of course, while APIs can be useful and powerful to accomplish many things, adding them isn't as simple as you might think.
As a result, there are three scenarios where you might be able to add an API to your systems. Some are easier than others. First, we have the bolt-on strategy. This is when you have an existing application, and add an API after the fact. This is often considered a brute force approach, but is the fastest way to get value from the API, since the underlying system is functional the whole time. This takes advantage of existing code and systems. You don't have to re-figure everything out. Unfortunately, poor architectural decisions and bad naming tends to seep through the system, and cause problems in the external interfaces, with helper libraries and all the supporting client code in pieces.
Next we have the other extreme. The greenfield strategy. This is when there's no underlying application or even necessarily business logic that you have to interact with. You have complete freedom and flexibility to do whatever you want, however you want to. This is a strategy behind "API first" or "Mobile first," and is the easiest scenario to develop an API. This offers us an opportunity that other strategies do not. Since you're starting from scratch, you can make use of technologies and concepts that may not have been available before. This can reinvigorate the team to learn new things and expand their skills.
This also tends to be the hardest option, because there is the biggest gap of time between when the requirements are defined and when you actually receive real business value. Finally, you have the facade strategy, which is the middle ground between greenfield and bolt-on. In this case you can take advantage of existing business systems, yet shape them to what you prefer and need. I'm working with one company, doing exactly this right now. They have a huge number of SOAP services that power their back end, and they're wrapping each of these with services with rearchitected REST services. This gives them the ability to keep working systems in place while making the underlying architecture better.
If you're not careful, it can be a place where you have naming translation and conversion layers that easily get out of control. In some cases, you can end-up with completely divergent mindsets in the system, which can make it look schizophrenic for people who can see both systems. Regardless of which strategy you choose, modeling will be the key to your success. We'll talk about that in the next video.
- The three approaches to adding an API
- Modeling tips
- Creating and grouping API methods
- Mapping activities to verbs and actions
- Validating your API
- Working with HTTP headers and response codes
- Layered systems
- Creating a uniform interface