Abstract of “Web API: The Good Parts” and How It Applies to Web Development — Part1
Introduction
Today, there are more and more situations where we developers have to develop Web APIs. Not only are services increasingly being integrated with each other, but also the backend of mobile applications, and more and more games are being integrated with servers. Furthermore, there will be no small number of cases where JSON will be used for asynchronous communication in web applications. It is no exaggeration to say that Web API is now a must-have field for software developers related to the Internet and the Web.
In “Web API: The Good Parts,” published by O’Reilly, a company that publishes software-related technical books, a freelance programmer thoroughly explains the concept and design of Web API while working on a variety of projects. Through this book, you can learn a wide range of API topics from basics to applications. If you are involved in API development, there is no harm in purchasing this book.
In this article, I would like to summarize this book and briefly explain how to apply the contents of this book to Web development. It is only my personal opinion and prejudice, but I would be very happy if you find it useful.
What is API?
The definition of “API” is very vague. The API that this book mainly targets is “an API that is invoked over a network using the HTTP protocol. Since it uses the HTTP protocol, the endpoint is specified by a URI. In simple terms, an API is a URI.
Simply put, an API is a web system that allows you to rewrite information on the server side or retrieve information placed on the server side by accessing a certain URI, and it is designed to be accessed by a program to use that data mechanically. APIs are not designed for direct human access via a browser.
For example, let’s consider an example using JSONPlaceholder, a free Fake API for API testing. First, access the following URI.
https://jsonplaceholder.typicode.com/posts/1After accessing here, you can retrieve information as follows.
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
"body": "quia et suscipit\\nsuscipit recusandae consequuntur expedita et cum\\nreprehenderit molestiae ut ut quas totam\\nnostrum rerum est autem sunt rem eveniet architecto"
}What is noteworthy here is that this information is displayed in a format called JSON, rather than the HTML used to display a web page in a browser. In other words, this URI is not intended to be directly displayed in a browser. This is why APIs are not designed to be directly accessed and used by humans; they are designed primarily for programs to retrieve data and use it for other purposes.
This book provides a thorough explanation of Web APIs, focusing mainly on those with JSON as the response format.
The Reason Why Developing Web API is Important
This book discusses the design of Web APIs. Why are Web APIs important? In a nutshell, exposing Web APIs has become increasingly important recently, and API design is very important considering that the API itself is now influencing the value and revenue of companies and services in some cases.
When APIs are in the hands of developers who have the skills to expose new systems and services, they themselves add value to the services and bring the power to further develop their core services.
Emerging services that are assumed to be used with APIs
In recent years, there has been an increase in the number of services that are designed to be used with APIs. Such services are often very simple in function and specialize in a single function. Twillo, for example, provides a service for easy implementation of functions such as auto-answering phone calls and sending/receiving SMS, which can be operated using a Web API. Such services are basically made available to the services that are the users by accessing the API via the Internet.
Such services appear to be more expensive than self-initiated operations when looking at cost alone. Web API plays a part in this trend.
Furthermore, even in services that users directly use, there is a growing trend toward services that delve into single functions that are supposed to be linked with other services. For example, Pocket is a bookmarking service that stores URIs for “reading later. Various smartphone applications that display web pages support Pocket’s API and implement a function that allows users to save the web page they are currently viewing in Pocket.
When you want to add a function that is already in a service, it is advantageous to link with a de facto or existing service if it has an API that is open to the public. By providing APIs, it will be possible to coexist and prosper with various services.
What Should We Release in Our API?
Assume you are already exposing your services. If you have not yet exposed your API to the Internet, you should consider exposing your API as already mentioned. But what should we expose with our API?
The short answer is that everything the service can do should be able to be done via API. For example, an e-commerce site should be able to search for and purchase products and obtain recommendations, and a real estate search site should be able to search for and narrow down properties and obtain floor plan information via API.
To be more specific, all the core parts of the service should be made available via API. For example, the core of an e-commerce site would include searching for and purchasing products.
Risks of exposing APIs
The first premise is that if your web service is not well known to the public, there is no need to design an API. On the other hand, if your web service is well-known and popular, more people will pay attention to it if you open your API to the public. In that case, you may be concerned that your data will be misused. This actually depends on how you operate.
Exposing an API does not mean accepting unlimited programmatic access. In many cases, APIs have a rate limit, or a limit on the number of accesses per user, so that if a large amount of accesses exceed that limit, a fee is charged, or the system is designed to prevent accesses beyond a certain level in the first place. For example, although Google discloses its search and translation function services via APIs, it is difficult to develop a search engine of the same scale as Google’s using Google’s search function.
The second premise is that people who are trying to steal data will try to steal information regardless of whether the API is public or private; there is a technique called web scraping, which mechanically accesses HTML pages and extracts information from them. This is commonly done by developers who desperately want information whose APIs are not publicly available. If they do not manage their own APIs, they may end up in a situation where they cannot control the acquisition of information.
Summary
In this article, the following contents were briefly explained based on O’Reilly’s technical book “Web API: The Good Parts”.
- What is Web API?
- Why it is important to design a Web API
- What you should expose in your API
- Risks of exposing APIs
I hope this article has given you a good understanding of Web API. In the next article, I will thoroughly explain API endpoint design and request format.
