1. API Design Demystified
The times have changedwe commute with Uber, overnight with Airbnb, pay with cryptocurrencies, and have breaking news at our fingertips via social media. We snap, chat, and share our lives in real-timeand these kinds of apps make it happen.
What drives most of these apps, however, are Application Programming Interfaces (APIs) , which are the glue of the connected world we live in. APIs are everywhere, from the doorbell in our smart homes to the traffic updates in our connected cars.
In web development , an API is a set of rules or contracts that dictate how consumers should interact with services by explicitly defining expected inputs and outputs. This is an architectural approach to abstract away the definition from the implementation.
Note
Although other uses of APIs include libraries, frameworks, and operating systems, the scope of this book will focus on the context of web-based APIs.
In this chapter, we will address the importance of APIs by understanding what they are as well as by getting introduced to the different architectural styles of web API design. We will then zoom into the REST architectural style and, by applying the six principles of REST, learn what it means to have a RESTful service.
The Importance of APIs
In todays modern, connected world, the API is one of the most critical elements of cloud-based services . Having billions of services out there for consumption requires good abstraction to promote compatibility, usability, and maintainability.
The API plays a crucial part in the integration of two systems , as it enforces a standardized communication link between them. For example, an electrical drill needs power from an electricity source for it to work. To be able to connect electrical equipment to power sources, we need a wall socket and a plug.
In this analogy, the wall socket is the API for providing electricity , and the drill is the consumer, as it uses a specific plug to be able to connect to power. One could, of course, connect the drilling machine directly to the wiring circuit, but it would require more manual work and be very unsafe. Imagine having to hardwire everything in your home; the result would be a mess. The point here is that having a plug and wall-socket mechanism drastically improves interoperability, allowing devices to be pluggable given a standard interface.
Web APIs are no different, as they ensure that systems can communicate seamlessly without the complexity of hardwiring. In fact, an API promotes accessibility by allowing multiple systems to use one implementation of business logic, regardless of their technology stack.
Imagine if the National Weather Service had to explicitly implement a system- integration point for each of its consumer systems. Updates and maintenance would be a nightmare, and that apparently wouldnt scale very well. Instead, implement an API to facilitate the flow of data in one standard way. Doing this also opens up the door to other possibilities, like integration with third-party systems, which can lead to opportunities to monetize on some of the internal components.
Other benefits of providing an API are control and analytics. It is vital that you secure sensitive endpoints, and having a mechanism to control access is paramount. There is a Dutch saying, meten is weten, which means measuring is knowing . Understanding how services are used provides useful insights on feasibility and potential optimizations.
APIs can be implemented in many different architectural styles . The most common styles that are used in the industry are RPC, WSDL, SOAP, and REST. When designing an API, it is important to use the right style for the problem at hand, as each of the styles has its advantages and disadvantages.
Note
To keep things in perspective, we will mainly focus on the REST-based architectural style. The others are only mentioned to broaden the understanding within the context of REST.
REST: The Good, Bad, and Ugly
REST is an acronym for Representational State Transfer , which is a style of architecture based on a set of predefined principles that describe how networked resources are defined and addressed . A service that implements the principles of REST is called a RESTful service .
It is common for web services to have clean, readable, and extensionless unique resource identifiers (URIs) or to return data in JavaScript Object Notation (JSON) format , but having extensionless URIs and endpoints that return vanilla JSON does not necessarily make the service a RESTful service.
Figure shows a typical output of a web service given a certain request and includes a dialog response from a developer who doesnt completely comprehend what a RESTful service is.
Figure 1-1
Example of a common assumption made by web-service developers
Lets take a look at a typical scenario involving a web service for managing a user profile. Here are some example endpoints for doing basic create, read, update, and delete (CRUD) operations on a profile, returning the results in Extensible Markup Language (XML) format :
/getAllProfiles
/getProfile?id=2
/createProfile
/deleteProfile?id=4
/updateProfile?name=eddy
These endpoints dont look too harmful. The first two endpoints, /getAllProfiles and /getProfile?id=2 , get all profiles and get a specific profile with an ID of 2, respectively. The /createProfile endpoint is responsible for creating a new profile, and as you might have guessed by now, the last two endpoints, /deleteProfile?id=4 and /updateProfile?name=eddy , delete and update a specific profile accordingly.
After some time in production, the business requested that more features be added, like the ability to retrieve additional friend information with a specific profile response as well as the capability to search for profiles by name. Typically, developers tend to just implement these capabilities in a quick and dirty fashion by adding two more endpoints to the collection, resulting in Version 2 of the service looking like the following:
/getAllProfiles
/getProfile?id=2
/getProfileWithFriends?id=2
/searchProfileByName?name=frank
/createProfile
/deleteProfile?id=4
/updateProfile?name=eddy
The additional endpoints may meet the requested business requirements but start to make the code very redundant by having the same type of information be served with slightly different aspects of it.
For Version 3 of the service, it is further requested that it support JSON responses on some of the current functionality in order for it to be RESTful. Keeping to the consistency of naming conventions and to prevent breaking changes (which can be a good thing), the developers might simply add more endpoints to the collection:
/getAllProfiles
/getAllProfilesJson
/getProfile?id=2
/getProfileJson?id=2
/getProfileWithFriends?id=2
/getProfileWithFriendsJson?id=2
/searchProfileByName?name=frank
/searchProfileByNameJson?name=frank
/createProfile
/deleteProfile?id=4
/updateProfile?name=eddy
As you can see, by just adding support for an additional output format, you can basically multiply the read operations . Going forward with this pattern would be a recipe for disaster, and one can imagine what the impact would be, given another simple request by the business.
