book

The Design of Web APIs

by Arnaud Lauret

October 2019

Intermediate to advanced

392 pages

11h 46m

English

Manning Publications

Read now

Unlock full access

Who should read this bookHow this book is organized: a roadmapAbout the codeliveBook discussion forumOther online resources

1.1 What is an API?1.1.1 An API is a web interface for software1.1.2 APIs turn software into LEGO® bricks1.2 Why API design matters1.2.1 A public or private API is an interface for other developers1.2.2 An API is made to hide the implementation1.2.3 The terrible consequences of poorly designed APIs1.3 The elements of API design1.3.1 Learning the principles beyond programming interface design1.3.2 Exploring all facets of API designSummary
2.1 The right perspective for designing everyday user interfaces2.1.1 Focusing on how things work leads to complicated interfaces2.1.2 Focusing on what users can do leads to simple interfaces2.2 Designing software’s interfaces2.2.1 Viewing an API as software’s control panel2.2.2 Focusing on the consumer’s perspective to create simple APIs2.3 Identifying an API’s goals2.3.1 Identifying the whats and the hows2.3.2 Identifying inputs and outputs2.3.3 Identifying missing goals2.3.4 Identifying all users2.3.5 Using the API goals canvas2.4 Avoiding the provider’s perspective when designing APIs2.4.1 Avoiding data influences2.4.2 Avoiding code and business logic influences2.4.3 Avoiding software architecture influences2.4.4 Avoiding human organization influences2.4.5 Detecting the provider’s perspective in the API goals canvasSummary
3.1 Introducing REST APIs3.1.1 Analyzing a REST API call3.1.2 Basic principles of HTTP3.1.3 Basic principles of REST APIs3.2 Transposing API goals into a REST API3.2.1 Identifying resources and their relationships with the API goals canvas3.2.2 Identifying actions and their parameters and returns with the API goals canvas3.2.3 Representing resources with paths3.2.4 Representing actions with HTTP3.2.5 REST API and HTTP cheat sheet3.3 Designing the API’s data3.3.1 Designing concepts3.3.2 Designing responses from concepts3.3.3 Designing parameters from concepts or responses3.3.4 Checking parameter data sources3.3.5 Designing other parameters3.4 Striking a balance when facing design challenges3.4.1 REST trade-off examples3.4.2 Balancing user-friendliness and compliance3.5 Understanding why REST matters for the design of any API3.5.1 Introducing the REST architectural style3.5.2 The impact of REST constraints on API designSummary
4.1 What is an API description format?4.1.1 Introducing the OpenAPI Specification (OAS)4.1.2 Why use an API description format?4.1.3 When to use an API description format4.2 Describing API resources and actions with OAS4.2.1 Creating an OAS document4.2.2 Describing a resource4.2.3 Describing operations on a resource4.3 Describing API data with OpenAPI and JSON Schema4.3.1 Describing query parameters4.3.2 Describing data with JSON Schema4.3.3 Describing responses4.3.4 Describing body parameters4.4 Describing an API efficiently with OAS4.4.1 Reusing components4.4.2 Describing path parametersSummary
5.1 Designing straightforward representations5.1.1 Choosing crystal-clear names5.1.2 Choosing easy-to-use data types and formats5.1.3 Choosing ready-to-use data5.2 Designing straightforward interactions5.2.1 Requesting straightforward inputs5.2.2 Identifying all possible error feedbacks5.2.3 Returning informative error feedback5.2.4 Returning exhaustive error feedback5.2.5 Returning informative success feedback5.3 Designing straightforward flows5.3.1 Building a straightforward goal chain5.3.2 Preventing errors5.3.3 Aggregating goals5.3.4 Designing stateless flowsSummary
6.1 Being consistent6.1.1 Designing consistent data6.1.2 Designing consistent goals6.1.3 The four levels of consistency6.1.4 Copying others: Following common practices and meeting standards6.1.5 Being consistent is hard and must be done wisely6.2 Being adaptable6.2.1 Providing and accepting different formats6.2.2 Internationalizing and localizing6.2.3 Filtering, paginating, and sorting6.3 Being discoverable6.3.1 Providing metadata6.3.2 Creating hypermedia APIs6.3.3 Taking advantage of the HTTP protocolSummary
7.1 Organizing an API7.1.1 Organizing data7.1.2 Organizing feedback7.1.3 Organizing goals7.2 Sizing an API7.2.1 Choosing data granularity7.2.2 Choosing goal granularity7.2.3 Choosing API granularitySummary
8.1 An overview of API security8.1.1 Registering a consumer8.1.2 Getting credentials to consume the API8.1.3 Making an API call8.1.4 Envisioning API design from the perspective of security8.2 Partitioning an API to facilitate access control8.2.1 Defining flexible but complex fine-grained scopes8.2.2 Defining simple but less flexible coarse-grained scopes8.2.3 Choosing scope strategies8.2.4 Defining scopes with the API description format8.3 Designing with access control in mind8.3.1 Knowing what data is needed to control access8.3.2 Adapting the design when necessary8.4 Handling sensitive material8.4.1 Handling sensitive data8.4.2 Handling sensitive goals8.4.3 Designing secure error feedback8.4.4 Identifying architecture and protocol issuesSummary
9.1 Designing API evolutions9.1.1 Avoiding breaking changes in output data9.1.2 Avoiding breaking changes to input data and parameters9.1.3 Avoiding breaking changes in success and error feedback9.1.4 Avoiding breaking changes to goals and flows9.1.5 Avoiding security breaches and breaking changes9.1.6 Being aware of the invisible interface contract9.1.7 Introducing a breaking change is not always a problem9.2 Versioning an API9.2.1 Contrasting API and implementation versioning9.2.2 Choosing an API versioning representation from the consumer’s perspective9.2.3 Choosing API versioning granularity9.2.4 Understanding the impact of API versioning beyond design9.3 Designing APIs with extensibility in mind9.3.1 Designing extensible data9.3.2 Designing extensible interactions9.3.3 Designing extensible flows9.3.4 Designing extensible APIsSummary
10.1 Overview of network communication concerns10.1.1 Setting the scene10.1.2 Analyzing the problems10.2 Ensuring network communication efficiency at the protocol level10.2.1 Activating compression and persistent connections10.2.2 Enabling caching and conditional requests10.2.3 Choosing cache policies10.3 Ensuring network communication efficiency at the design level10.3.1 Enabling filtering10.3.2 Choosing relevant data for list representations10.3.3 Aggregating data10.3.4 Proposing different representations10.3.5 Enabling expansion10.3.6 Enabling querying10.3.7 Providing more relevant data and goals10.3.8 Creating different API layersSummary
11.1 Adapting communication to the goals and nature of the data11.1.1 Managing long processes11.1.2 Notifying consumers of events11.1.3 Streaming event flows11.1.4 Processing multiple elements11.2 Observing the full context11.2.1 Being aware of consumers' existing practices and limitations11.2.2 Carefully considering the provider’s limitations11.3 Choosing an API style according to the context11.3.1 Contrasting resource-, data-, and function-based APIs11.3.2 Thinking beyond request/response- and HTTP-based APIsSummary
12.1 Creating reference documentation12.1.1 Documenting data models12.1.2 Documenting goals12.1.3 Documenting security12.1.4 Providing an overview of the API12.1.5 Generating documentation from the implementation: pros and cons12.2 Creating a user guide12.2.1 Documenting use cases12.2.2 Documenting security12.2.3 Providing an overview of common behaviors and principles12.2.4 Thinking beyond static documentation12.3 Providing adequate information to implementers12.4 Documenting evolutions and retirementSummary
13.1 The API lifecycle13.2 Building API design guidelines13.2.1 What to put in API design guidelines13.2.2 Continuously building guidelines13.3 Reviewing APIs13.3.1 Challenging and analyzing needs13.3.2 Linting the design13.3.3 Reviewing the design from the provider’s perspective13.3.4 Reviewing the design from the consumer’s perspective13.3.5 Verifying the implementation13.4 Communicating and sharingSummary

Content preview from The Design of Web APIs

5 Designing a straightforward API

This chapter covers

Crafting straightforward representations of concepts
Identifying relevant error and success feedback
Designing efficient usage flows

Now that you have learned to design APIs that actually let consumers achieve their goals, you have a solid foundation in API design. Unfortunately, only relying on the basics does not mean that consumers will actually be able to use the “APIs that do the job.” Remember the UDRC 1138 shown in figure 5.1? It is possible to design a terrible interface that does the job.