The Design of Web APIs, Second Edition (MEAP) (Arnaud Lauret) (Z-Library)

The Design of Web APIs, Second Edition 1. welcome 2. 1_What_is_API_design? 3. 2_Analyzing_needs 4. 3_Observing_operations_from_the_REST_angle 5. 4_Representing_operations_with_HTTP 6. 5_Modeling_data 7. index

welcome Thank you for purchasing The Design of Web APIs, Second Edition. Web APIs are everywhere; we use them all the time, often without even realizing it. Whether sharing a photo on social media or hailing a ride through an app, web APIs are crucial in making it happen. For developers, APIs are essential as most modern systems rely on multiple software components communicating with each other. We need them to build simple web applications to complex distributed systems. APIs are also products in their own right, as exemplified by Stripe or Twilio. Even government agencies rely on APIs to power their digital services. The design quality is crucial for web APIs, whether seen as technical interfaces or products, used by a single application or multiple, or created for internal use or third-party. Poorly designed public or private APIs can harm developers' productivity, system performance and integrity, end-users experience, and organization’s revenue. This book aims to help you develop an API designer’s mindset and design exceptional web APIs, specifically REST APIs. In these chapters, we will explore the true nature of API design as both a result and a process. We will learn how to analyze and evaluate requirements to identify the API capabilities, discover HTTP and REST, and understand how to use them to represent these capabilities. We will discuss how to create interoperable and user-friendly APIs, ensuring that anyone can instantly use the API’s data and operations. We will also learn how to integrate various constraints, especially security, into our design. Additionally, we will focus on handling modifications and preventing breaking an API design unintentionally or breaking it intentionally when it makes sense. Furthermore, we will learn how to become efficient API designers by learning various principles and recipes for making design decisions when faced with new problems. We will learn to convince others (and ourselves) that our design decisions are correct. I am writing the second edition of this book to address what was not working

well in the first edition and expand it. I also reorganize the content to make it easier to follow and integrate new ideas and feedback received from readers. I am keeping the spirit of the first edition but rewriting everything. In a way, this is almost a new book. Your feedback is essential to make this new edition the best companion on your journey of API design; I hope you’ll add your comments to the Livebook discussion forum. — Arnaud Lauret In this book welcome 1 What is API design? 2 Analyzing needs 3 Observing operations from the REST angle 4 Representing operations with HTTP 5 Modeling data

1 What is API design? This chapter covers Explaining what web APIs are Realizing the importance of the design of web APIs Clarifying who designs web APIs, which ones should be designed, and when Comprehending the purpose of web API design Overviewing the web API design process What magic allows us to share pictures on social media, check bank balances, and hail cabs from our phones? How can developers quickly add telecom or payment services to their apps without expertise? What do basic web or mobile apps need to display data to users? Web application programming interfaces or APIs. Web APIs are essential in our connected world as they serve as technical interfaces or products for various systems, organizations, and companies, from small startups to large corporations and government entities. API design is crucial for the success of any system, whether its APIs are visible or hidden. Poorly designed APIs can negatively impact developers' productivity, the system’s performance and integrity, end-users experience, and revenue. Learning web API design requires a shared understanding of API and design concepts. This chapter covers the different aspects of web APIs, the importance of their design, and who designs them. It also provides an overview of the API design process and our approach that separates concerns to facilitate learning and execution. 1.1 What is a web API? Web APIs are software interfaces that allow remote communication between applications. They are invaluable because they don’t require knowledge of

the underlying code; anyone can use them, not just their creators. 1.1.1 A remote web interface for applications A web API enables one application (the server, backend, or provider) to expose functions or operations that other applications (the client or consumer) can use, call, or consume remotely over a network using web technologies. For example, many mobile applications rely on a remote server application accessible via the internet and its web API to retrieve, send, or process data. Figure 1.1 Using the Socnet mobile application

Figure 1.1 shows what happens when a user of the Socnet social network shares a photo via its mobile application. The user takes a photo, types a message, and taps the "Share" button. The mobile application calls the "Share" operation of the server application’s web API to send the message and the photo via the internet network. The server application identifies the user’s friends in the photo and stores the message, the identified friends, and the photo. Other users of the Socnet mobile application can see the shared messages, photos, and identified people on their timelines thanks to a call to the "Timeline" operation of the same web API.

When a mobile application communicates with a server application via its web API, it leverages the same mechanism as when a web browser retrieves and displays an HTML page of a basic website. That’s the origin of the "web" in web APIs. Note There are different types of web APIs, such as REST, SOAP, GraphQL, and gRPC. No worries if those names mean nothing to you; this book focuses on REST web APIs, but many principles presented here apply to other web APIs. What is a REST API and why we focus on it will be explained in later chapters. Web APIs can be exposed on any network and consumed by any application. Socnet can use the same API in their web application, create a batch server to regularly call the timeline operation, and expose the next API version on their local network for quality checks before deploying to production. 1.1.2 An interface to an implementation We often use "web API" as a convenient shortcut to designate an application exposing an API. However, the "web API" is only a part of it. Reading this book, we should not confound the web API with the application’s implementation or actual code. A web API is an interface to an implementation and usually hides implementation details. Figure 1.2 Comparing a restaurant and an application exposing a web API

As shown in figure 1.2, we can compare an API and its implementation to a restaurant. The API is the waitperson who takes your order and brings it back to you. The implementation is what happens in the kitchen. You don’t need to know who is in the kitchen, the recipe, its ingredients, how it’s cooked, and even if it’s cooked there. You just need to know that you’ll get the dish you ordered. The Socnet mobile developers code what happens on a tap of the "share" button without knowing what happens behind the API. Knowing which database is used, how data is organized, or which face detection algorithm is

useless to them. They only need to code the API call, providing the expected data, and the API implementation takes care of the rest. 1.1.3 An interface for others The fact that someone coding an application using a web API doesn’t need to know how it is implemented has exciting consequences: it enables collaboration within an organization and allows people outside the organization to use and even pay for APIs. At Socnet, three teams efficiently develop the backend API, mobile app, and website with minimal need for synchronization or shared knowledge. The mobile and web teams only need to know the services or features provided by the backend API, not how it is coded. To deliver a robust face detection feature, the backend API team leveraged the "Face Detection API" from "Image Processing As A Service" (for which they pay a subscription). Additionally, Socnet set up a "Search API" for selected partners willing to pay for access to more data. Figure 1.3 What is an internal, external, private, partner, or public API?

The APIs involved here represent three levels of API openness (or closeness): private (Backend API), partner (Search API), and public (Face Detection API). Internal and external may be used to qualify private and partner/public APIs, respectively. These terms may also indicate that an API is exposed on a local network or the internet. Figure 1.3 shows two tables disambiguating all these terms. Most web APIs are private, and there are millions of them, as any company with an IT system will need them. While many are consumed by those who create them, others across the organization often use them.

Many organizations use partner or public APIs from others, which may be qualified as products, and their access is often paid. These APIs could be exposed by commercial or open-source software installed on their infrastructure. Increasingly, companies offer "as-a-service" products accessible via websites, mobile apps, and APIs, and sometimes the API is the only channel. Examples include payroll, retail, financial services, payments, telecommunications, project management, development, and cloud infrastructure. Even not-so-digital companies and government agencies offer partner or public APIs. Whatever we need, "There’s an API for that." 1.2 Why does API design matter? The term "design" can designate both the process we go through to decide what an API does, how it does it, and how it looks like and the final result, the API itself. As a result, the design of a web API matters because it affects its consumers and provider. This section leverages a real-world analogy to demonstrate how. Then, it explains how this applies to web APIs and why designing them well is essential. 1.2.1 The design of any interface affects its users and creator Figure 1.4 shows a Kitchen Radar. What is it, and how to operate it? Its interface doesn’t help us figure this out. Pushing the "MAG." button seems to start it, but it stops when we release it. Figure 1.4 The Kitchen Radar

According to the user manual, shown in figure 1.5, The Kitchen Radar, named "Radar" for historical reasons, can heat food. The "MAG." button turns the magnetron on and off. When on, microwaves heat the food in the oven’s cavity. To modulate the heating power, users must hold the button for a given time (e.g., 13 seconds) and release it for the same time, as indicated in the "Heating power cheat sheet." This Kitchen Radar is a microwave oven proposing a terrible user experience despite the user manual, thanks to its cryptic, inside-out, and absurd interface. It requires users to become experts in magnetrons and time themselves

pushing and releasing the button. It’s complicated and annoying to use. And there may be reliability and safety issues. How will the magnetron and overall circuitry react to being turned on and off at a random or too high- speed rate? Ultimately, who would buy this product? Figure 1.5 The Kitchen Radar’s user manual 1.2.2 The design of any web API affects both consumers and provider

The design of the "Kitchen Radar" interface is an exaggeration of the worst possible flaws you could find in an everyday object. And yet, I’ve come across private, partner, or public APIs whose designs look like this; they were hard to understand or use or were exposing inner workings. Such API designs negatively impact consumers and providers. If an API is hard to understand, its purpose and features unclear, developers may spend extra time integrating it, making more errors, and asking many questions. Potential users may pass by if the API is partner or public, leading to less revenue for the provider. APIs that are easy to understand can still be hard to use. Developers may spend extra time writing code to orchestrate complex API call flows, resulting in more errors. Due to this complexity, they may make many API calls, leading to unexpected extra load and costly cloud infrastructure billing. If the API is public or partner-based, users may cancel their subscription when they realize how complicated it is. An API design exposing the implementation’s inner workings is often hard to use and understand. But more than that, it creates tight coupling between applications, prolongs modification, and augments the risk of errors or crashes. 1.2.3 Taking care of design unleashes the power of APIs Taking care of web API design prevents the previous section’s issues and unleashes their power. Here are some benefits you may witness: Better developer productivity: Well-designed APIs are much easier to understand and use. Additionally, they offer greater flexibility and interoperability, requiring less effort to interpret their data. Developers can integrate them into their applications quickly and with minimal code. More modular and efficient systems: Well-designed APIs allow the creation of decoupled systems where the applications consuming and providing APIs have limited dependencies. They may also contribute to reducing infrastructure usage.

Faster time to value: Developers can achieve their goals quickly by using well-designed APIs that are versatile and reusable in various contexts, allowing for creating innovative solutions without rebuilding everything. Better end-user experience: Well-designed APIs provide features efficiently and flexibly that can contribute to creating an outstanding experience for the end-users of the applications using them. More API-generated value: Well-designed APIs can increase indirect and direct value by reducing development costs and increasing revenue through customer satisfaction. 1.3 Who designs web API? API design matters, but who can design web APIs? You! But probably not alone. API design requires diverse skills and knowledge, often resulting from different people’s work. Those with API design skills, IT and subject-matter knowledge, and influence can all contribute directly or indirectly to the design of an API. 1.3.1 Those with API design skills API designers lead the discussions and hold the pen when designing web APIs. They come from various backgrounds and have different skill sets. I’ve worked with, advised, and trained API designers from various profiles, including developers, tech leads, architects, business analysts, tech writers, QA engineers, product managers, and product owners. Some started as juniors, while others began after long careers. While having a thorough understanding of the subject matter and software is undoubtedly an advantage, it is not a requirement for designing APIs. As an API designer, you only need to know the fundamental principles of API design and how to get the necessary information. This book will teach you that. 1.3.2 Those with subject-matter knowledge

APIs solve specific problems like social networking, banking, product catalogs, or database as a service system administration. As an API designer, you don’t need to be an expert in the subject matter. Like when creating any application, by interviewing SMEs (subject matter experts), you can ensure your API accurately represents the business domain and its problems. 1.3.3 Those with software knowledge Web APIs are programming interfaces for software. Designing one requires familiarity with web API-based systems and specific knowledge about the system that will expose the API. Knowing the principles, practices, and limitations of web API-based software in general and web and mobile applications, in particular, will significantly help design realistic, implementable, and technically usable APIs. For example, some API design patterns may kill a smartphone battery, and others can make an API more effortless to use across many systems. We’ll uncover the typical general software concerns you should consider when designing an API and how to avoid or mitigate them in your designs. Knowing the system behind a web API can be helpful. For instance, if the application responsible for detecting faces takes a minute to identify people in a photo, this should be considered when designing the API. We’ll learn the right questions to ask technical leads and architects to uncover such details and how to leverage this knowledge sensibly to avoid revealing internal workings. 1.3.4 Those with influence An API will be the result of a sum of various influences. As an API designer, you’ll have some control over some of these, while others are out of your hands. Even the most knowledgeable API designers must consider feedback from peers, reviewers, security teams, and, most importantly, consumers. Knowing how to integrate feedback is vital to creating an API that satisfies all parties involved. 1.4 When designing web APIs?

API design is an essential task that requires careful consideration. When to undertake this task is a question that often arises. Should we design all APIs? Should modifications to APIs also be designed? When is the best time to design an API? The answer is simple: we should design all types of APIs, such as internal, external, private, partner, or public APIs, as well as any modifications to web APIs. Moreover, we must prioritize API design before developing the implementation. 1.4.1 When creating any API Should we only design partner or public APIs because they are more visible than private ones? No. They all are essential, and we must design them all, whoever consumes them and wherever they are exposed. It is now common for organizations to provide partner or public APIs to third parties. Neglecting their design or brutally turning non-designed private APIs into partner or public APIs will lead to terrible APIs and serious consequences, as seen in section 1.2.2. For example, ignoring partner API design can lead to lengthy and costly integration projects, while a poorly designed public API may have no customers. Neglecting the design of private APIs can also lead to the issues we’ve uncovered in section 1.2.2. Even if we’re the only creators and consumers, poor design impacts code and productivity, leading to missed milestones, fewer features, bugs, and revenue loss. Finally, using private APIs to improve your skills and prepare for designing APIs for others is crucial. You will likely create more APIs for personal use than those you provide to other teams; most will be private rather than public or partner ones. Practicing with private APIs will help you make better decisions with confidence. Jeff Bezos' mandate Around 2002, Jeff Bezos, former CEO of Amazon, issued a mandate stating that all teams must communicate through "service interfaces" (they were not called API then). And that all those "service interfaces" must be designed

from the ground with externalization in mind, as each could be put in customers' hands anytime after its creation. This strategy was key to Amazon’s success. 1.4.2 When making any modification It’s essential to design APIs during initial creation and for any modifications, even the most minor ones. The reason for this is the same as when creating them, but the stakes are higher. Carelessly modifying an existing API that applications already use can lead to disastrous consequences. It may break their code, causing crashes or data corruption. And even if, under certain circumstances, it is possible to introduce modifications that will break consumer code without much consequence, we must still consciously design them to evaluate the impacts. 1.4.3 Before developing the implementation API design precedes implementation and occurs repeatedly throughout the API lifecycle, the various stages an API will go through, from its inception to its consumption. Figure 1.6 The lifecycle of an API