book

The Design of Web APIs, Second Edition

Name: The Design of Web APIs, Second Edition
Author: Arnaud Lauret
ISBN: 9781633438149

by Arnaud Lauret

June 2025

Intermediate to advanced

536 pages

16h 54m

English

Manning Publications

Audiobook available

Read now

Unlock full access

The Design of Web APIs, Second Edition
copyright
contents
Praise for the first edition
dedication
foreword
preface
acknowledgments
about this book
about the author

about the cover illustration
1 What is API design?
1.1 What is a web API?1.1.1 A web API is a remote interface for applications1.1.2 A web API uses the HTTP protocol1.1.3 A web API is an interface to an implementation1.1.4 A web API is an interface for others1.2 Why does the design of any API matter?1.2.1 What if a terrible API was a kitchen appliance?1.2.2 Poor web API design affects developers and architecture1.2.3 Poor web API design puts security and infrastructure at risk1.2.4 Poor web API design affects end-user and third-party experiences1.2.5 Taking care of design unleashes the power of APIs1.3 When to design web APIs?1.3.1 Any new API must be designed1.3.2 Any modification of any existing API must be designed1.3.3 Design happens between choosing to create an API and coding it1.4 Who designs web APIs?1.4.1 The three profiles needed to design an API1.4.2 The stakeholders influencing API design1.5 How do we design web APIs?1.6 Designing APIs step by step1.6.1 Identifying the API capabilities1.6.2 Designing the programming interface1.6.3 Describing the programming interface1.6.4 Enriching API design artifacts1.7 Designing APIs layer by layer1.7.1 Designing a versatile API that does the right job1.7.2 Designing a user-friendly and interoperable API1.7.3 Integrating constraints in an API design1.7.4 Using a reasoned and continuously improving design process
Part 1 Fundamentals of API design
2 Identifying API capabilities
2.1 An overview of identifying API capabilities2.1.1 Starting with the output of the Define stage2.1.2 Analyzing what users need to achieve2.1.3 Identifying versatile operations to achieve use cases2.1.4 Keeping programming interface design concerns for later2.1.5 Clarifying the subject matter and input2.2 Introducing the API Capabilities Canvas2.2.1 How does the API Capabilities Canvas work?2.2.2 Tools to use along with the API Capabilities Canvas2.3 Walking the nominal paths2.3.1 Identifying users2.3.2 Listing use cases2.3.3 Decomposing use cases in steps2.3.4 Determining inputs and success outcomes2.3.5 Spotting missing elements with sources and usages2.3.6 Analyzing the spotted elements2.4 Walking the alternative and failure paths2.4.1 Analyzing failures for each step2.4.2 Adding alternative branches on each use case2.4.3 Analyzing the alternative users and use cases2.5 Refining steps to identify operations2.5.1 Differentiating steps and operations2.5.2 Identifying unique and versatile operations2.6 Focusing on the proper needs2.6.1 Staying within the Define stage’s needs scope2.6.2 Focusing on the proper perspectives2.6.3 Asking why to investigate any problem2.7 Avoiding integrating too specific consumers’ perspective2.7.1 Avoiding mapping consumers’ UI2.7.2 Avoiding integrating consumers’ business logic2.8 Avoiding exposing the provider’s perspective2.8.1 Avoiding exposing the provider’s data organization2.8.2 Avoiding exposing the provider’s business logic2.8.3 Avoiding exposing the provider’s software architecture
3 Observing operations from the REST angle
3.1 An overview of programming interface design3.1.1 Introducing the basics of the HTTP protocol3.1.2 Introducing the basics of REST APIs3.1.3 Contrasting REST with non-HTTP-compliant web APIs3.1.4 How do we design a REST programming interface?3.1.5 Why not discuss HTTP and REST when identifying capabilities?3.2 Observing the API Capabilities Canvas from the REST angle3.2.1 Reorganizing and expanding the API capabilities canvas3.2.2 How to observe operations from the REST angle3.3 Identifying resources and their relations3.3.1 What is a resource?3.3.2 Identifying an operation’s resource3.3.3 Tweaking an operation’s description to identify resource3.3.4 Identifying resource relations3.3.5 Using patterns and recipes to identify resources and relations3.4 Identifying resource actions3.4.1 What is an action, and how can it be identified?3.4.2 Listing an action’s inputs3.4.3 Dealing with the operation’s resource when listing an action’s inputs3.4.4 Listing an action’s outputs3.4.5 Dealing with contradictory successes and failures when listing outputs
4 Representing operations with HTTP
4.1 Representing operations with HTTP4.1.1 What an operation looks like with HTTP4.1.2 How to represent operations with HTTP4.2 Representing resources with paths4.2.1 What is a resource path?4.2.2 Designing meaningful resource paths4.2.3 Targeting specific elements with path parameters4.2.4 Showing resource relationships with a hierarchy4.2.5 Representing lists and their elements4.3 Representing actions with HTTP methods4.3.1 Determining which HTTP methods to use4.3.2 Choosing HTTP methods to represent actions4.3.3 Representing search, read, and delete actions4.3.4 Representing update actions4.3.5 Representing create actions4.3.6 Mapping typical operations to HTTP4.4 Choosing input data locations in HTTP requests4.4.1 Where to put input data in an HTTP request4.4.2 An overview of input data natures4.4.3 Choosing a location for resource identifiers4.4.4 Choosing a location for resource representations4.4.5 Choosing a location for resource modifiers4.4.6 Hesitating between resource identifiers and modifiers4.4.7 Choosing input data locations for typical operations4.5 Representing output types with HTTP statuses4.5.1 What is an HTTP status?4.5.2 Choosing HTTP statuses for outputs4.5.3 Choosing successful HTTP statuses for read operations4.5.4 Choosing successful HTTP statuses for delete operations4.5.5 Choosing successful HTTP statuses for update operations4.5.6 Choosing successful HTTP statuses for search operations4.5.7 Choosing successful HTTP statuses for create operations4.5.8 Choosing error HTTP statuses4.5.9 Ensuring exhaustive error-handling4.5.10 Choosing HTTP statuses for typical operations4.6 Choosing output locations in HTTP responses4.6.1 Where to put data in an HTTP response4.6.2 Filling the output data gaps4.6.3 Choosing output locations4.6.4 Choosing output data locations for typical operations4.7 Representing a “do” operation with HTTP4.7.1 Using an action resource4.7.2 Turning the action into a business concept4.7.3 Focusing on the result4.8 Using the REST architectural style principles for API design4.8.1 Introducing the REST architectural style4.8.2 Applying REST principles to API design4.8.3 Debates about what is (or is not) REST
5 Modeling data
5.1 An overview of data modeling5.1.1 Which data are we modeling?5.1.2 Introducing the JSON portable data format5.1.3 Modeling data5.2 Designing theoretical resource data models5.2.1 Determining a resource’s structure5.2.2 Choosing an object resource’s properties5.2.3 Choosing a property name and type5.2.4 Indicating required properties5.2.5 Listing and modeling properties efficiently5.3 Designing inputs and outputs data models5.3.1 Designing a read operation’s inputs and success outputs5.3.2 Designing a search operation’s inputs and success outputs5.3.3 Designing a create operation’s inputs and success outputs5.3.4 Designing an update operation’s inputs and success outputs5.3.5 Designing a delete operation’s inputs and success outputs5.3.6 Designing a temporary error data model5.4 Streamlining input and output data modeling5.4.1 Designing and using the complete, summarized, minimal, and identifier models5.4.2 Designing and using the creation, replacement, and modification models5.4.3 Modeling data for “do” operations5.4.4 Differentiating similarly named elements5.5 Using data to ensure completeness and proper focus5.5.1 Spotting missing elements by analyzing input sources and output usages5.5.2 Ensuring complete business error-handling5.5.3 Focusing on the proper elements
6 Describing HTTP operations with OpenAPI
6.1 Overview of describing the programming interface6.1.1 Introducing the OpenAPI Specification6.1.2 Using OpenAPI during design6.1.3 Introducing the YAML format6.1.4 Contrasting an OpenAPI document with our API spreadsheet6.1.5 Describing the programming interface while designing it6.2 Authoring OpenAPI documents6.2.1 Introducing the specification-first and code-first approaches6.2.2 Contrasting the specification-first and code-first approaches6.2.3 Picking an OpenAPI editor6.2.4 Choosing an OpenAPI version6.2.5 Choosing between JSON and YAML6.3 Describing HTTP operations with OpenAPI6.4 Describing resource paths6.4.1 Initiating an OpenAPI document6.4.2 Describing a path6.4.3 Describing a path with path parameters6.5 Describing operations6.6 Describing operation inputs6.6.1 Describing query parameters and other non-body parameters6.6.2 Describing request bodies6.7 Describing operation output HTTP status codes6.7.1 Describing an output case type with an HTTP status6.7.2 Dealing with outputs sharing the same HTTP status code6.8 Describing operation output contents6.8.1 Describing response bodies6.8.2 Dealing with responses without bodies6.8.3 Describing response headers
7 Describing data with JSON Schema in OpenAPI
7.1 An overview of describing data7.1.1 Introducing JSON Schema7.1.2 Contrasting OpenAPI and JSON Schema with our API spreadsheet7.1.3 Describing data while designing it7.2 Authoring a JSON Schema data model in OpenAPI7.3 Adding complete resource data models to the OpenAPI document7.3.1 Choosing a location for the resource model in the OpenAPI document7.3.2 Initiating the resource model description7.4 Describing complete resource data models with JSON Schema7.4.1 Describing an object7.4.2 Adding properties to an object7.4.3 Describing an atomic property7.4.4 Describing an object property7.4.5 Describing an array property7.4.6 Stating which properties are required7.5 Describing operation input and output data7.6 Describing operation non-body data7.6.1 Describing non-body request parameters with inline schemas7.6.2 Tweaking non-atomic parameter serialization7.6.3 Describing response headers with inline schemas7.7 Describing operation body data7.7.1 Using references to resource models in response bodies7.7.2 Deriving the complete resource model to create other reusable models7.7.3 Using references to resource models in request bodies7.7.4 Mixing inline schema and reference
Part 2 User-friendly, interoperable API design
8 Designing user-friendly, interoperable data
8.1 The user-friendliness and interoperability layer of API design8.1.1 Overview of the API user experience8.1.2 Which users’ experiences matter to us?8.1.3 How API design user-friendliness and interoperability affect UX8.2 What makes data user-friendly and interoperable?8.2.1 User-friendly data meets user needs8.2.2 User-friendly data helps us find and interpret information8.2.3 User-friendly data limits consumers’ work8.2.4 User-friendly data is consistent8.2.5 Interoperable data is consistent and standard8.3 When and how to design user-friendly, interoperable data8.3.1 Which data must be user-friendly and interoperable?8.3.2 When to address user-friendly, interoperable data8.3.3 How to design user-friendly, interoperable data8.4 Selecting and crafting ready-to-use data8.4.1 Choosing simple and meaningful but useful data8.4.2 Adding supporting data to ease and secure interpretation8.4.3 Adding processed data to reduce consumer effort8.4.4 Choosing well-known or standard resource identifiers8.4.5 Choosing well-known or standard data8.5 Choosing user-friendly, interoperable atomic types and formats8.5.1 Considering formatting numbers as strings8.5.2 Managing non-human-readable codes8.5.3 Managing dates and times8.6 Organizing data8.6.1 Grouping data with objects8.6.2 Grouping data with arrays8.6.3 Sorting data in arrays and objects8.7 Choosing data granularity and scope8.7.1 Considering relevance, not size8.7.2 Embedding lists in a resource model8.7.3 Modeling embedded resources8.8 Designing user-friendly names8.8.1 When to design user-friendly names8.8.2 Designing simple, clearly organized, concise names8.8.3 Learning by fixing non-user-friendly names8.9 Aiming for consistency and standardization8.9.1 Seeking local, domain, or global standardization8.9.2 Using well-known or standard identifiers consistently8.9.3 Defining a naming pattern for identifiers8.9.4 Naming, typing, and structuring consistently
9 Designing user-friendly, interoperable operations
9.1 What makes operations user-friendly and interoperable?9.1.1 User-friendly operations expose clear capabilities that meet the needs9.1.2 User-friendly operations use user-friendly data and are helpful9.1.3 User-friendly, interoperable operations are consistent and standard9.2 When and how to design user-friendly, interoperable operations9.2.1 When to take user-friendly, interoperable operations into consideration9.2.2 How to design user-friendly, interoperable operations9.3 Designing easy-to-understand, guessable operations9.3.1 Combining meaningful resource paths and HTTP compliance9.3.2 Creating predictable resource paths9.3.3 Crafting short but accurate resource paths9.4 Requesting easy-to-provide inputs9.4.1 Using typical and HTTP-compliant input locations9.4.2 Mapping inputs to outputs9.4.3 Requesting well-known or standard data9.4.4 Minimizing inputs with default and server-processed data9.5 Returning ready-to-use successful responses9.5.1 Choosing adequate HTTP status and HTTP-compliant data locations9.5.2 Returning sufficiently informative data9.6 Filtering, sorting, and paginating lists9.6.1 Designing guessable filters that map returned data9.6.2 Designing flexible filters9.6.3 Enabling free search and complex logic with a q filter9.6.4 Minimizing filters9.6.5 Enabling sort with helpful defaults9.6.6 Paginating lists9.6.7 Returning filter, sort, and pagination metadata9.7 Adapting request and response data9.7.1 Handling different data formats9.7.2 Translating data and adapting to locale9.7.3 Tweaking returned data9.8 Handling consumer errors gracefully9.8.1 Limiting consumer errors9.8.2 Using adequate HTTP status codes9.8.3 Providing informative, problem-solving feedback9.8.4 Returning machine-readable feedback9.8.5 Returning an exhaustive list of errors9.8.6 Using standards9.9 Avoiding hiding multiple capabilities in a single operation9.9.1 Reconsidering request and response data granularity9.9.2 Reconsidering an operation’s purpose9.10 Aiming for consistency and standardization9.10.1 Using standardized data consistently9.10.2 Adopting standardized behavior consistently9.10.3 Offering standardized features consistently
10 Designing user-friendly, interoperable operation flows
10.1 What makes an operation flow user-friendly and interoperable?10.1.1 Using user-friendly, interoperable elements10.1.2 Being designed as a whole10.1.3 Being concise and flexible10.1.4 Meeting user needs within the flow10.1.5 Being helpful across operations10.1.6 Aiming for consistency and standardization10.2 When and how to optimize flows10.2.1 When to consider flow optimization10.2.2 How to optimize flows10.3 Designing concise, error-limiting, flexible flows10.3.1 Introducing the money-transfer use case10.3.2 Uncovering operation flow problems10.3.3 Calling read and search operations once10.3.4 Enhancing operations with use-case-specific features10.3.5 Adding use-case-specific operations10.3.6 Combining operations into a use-case-specific operation10.3.7 Adding use-case-specific output data10.3.8 Avoiding constraining consumer flow10.4 Designing flexible data-saving flows10.4.1 Introducing the “Open an account” use case10.4.2 Understanding how data-saving constrains consumer flow10.4.3 Enabling partial data-saving10.4.4 Carefully aggregating saving operations10.4.5 Smoothing validation and separating it from completion10.4.6 Enabling full and partial data-saving flows10.4.7 Redirecting the consumer to the finalized resource
11 Designing user-friendly, interoperable APIs
11.1 What makes an API user-friendly and interoperable?11.1.1 Having a clear purpose that meets focused needs11.1.2 Enabling discovery and navigation11.1.3 How to create user-friendly, interoperable APIs11.2 Creating one or multiple APIs11.2.1 When to discuss API granularity11.2.2 Identifying independent sets of operations11.2.3 Keeping in mind that sub-APIs can be related11.3 Clarifying the API’s purpose with its name11.3.1 When to choose an API name11.3.2 Choosing an API name11.3.3 Adding the API name to the API base path11.4 Enabling interoperable API browsing with HTTP and hypermedia APIs11.4.1 Listing a resource’s operations with the OPTIONS HTTP method11.4.2 Providing pagination, formats, and resources links with the Link header11.4.3 Using hypermedia formats for relations and actions11.4.4 Using content negotiation to select hypermedia or plain JSON format11.4.5 Ensuring that subject matter data is always available11.4.6 Considering browsing capabilities
Part 3 Constrained API design
12 Designing a secure API
12.1 Overview of API security12.1.1 What happens during an API call?12.1.2 Uncovering design-related API security problems12.2 When and how to handle security during design12.2.1 When to consider security during API design12.2.2 How API design contributes to API security12.3 Exposing only the necessary data and operations12.3.1 What are sensitive operations and data?12.3.2 Challenging sensitive and non-sensitive data and operations12.3.3 Modifying data to make it less sensitive or non-sensitive12.3.4 Splitting an operation to separate concerns12.3.5 Separating sensitive operations in dedicated APIs12.4 Ensuring that implemented operations behave according to context12.4.1 Describing who sees or does what12.4.2 Describing what list or search operations return12.4.3 Describing how inputs narrow access12.4.4 Describing all expected implementation checks and behaviors12.4.5 Narrowing access by design12.5 Ensuring data integrity12.5.1 Corrupting data with regular API calls12.5.2 Correctly implementing HTTP methods12.5.3 Preventing request replay12.5.4 Enabling and enforcing conditional updates12.6 Avoiding protocol- or architecture-based security problems12.6.1 What may not be secured on an API call over HTTPS12.6.2 Dealing with sensitive search parameters12.6.3 Dealing with sensitive resource IDs12.6.4 Integrating data encryption or signing in the design12.7 Limiting consumer access with scopes12.7.1 Limiting access to an operation with a scope12.7.2 Measuring the importance of scopes and their design12.8 Designing scopes12.8.1 Creating operation-based scopes12.8.2 Creating resource-, concept-, or use-case-based scopes12.8.3 Creating scopes for read or write operations12.8.4 Creating end-user- or consumer-based scopes12.8.5 Tweaking operation behavior with scopes12.8.6 Deciding which scope types to use12.9 Describing scopes with OpenAPI12.9.1 Defining scopes12.9.2 Using scopes12.10 Erroring securely12.10.1 Handling token-related errors12.10.2 Handling missing scopes or permissions12.10.3 Avoiding disclosing implementation details on server errors12.10.4 Providing implementation details in response descriptions in OpenAPI12.10.5 Enforcing expected error data with JSON Schema
13 Designing an efficient API
13.1 An overview of API efficiency13.1.1 How an API can be inefficient13.1.2 When to be concerned about efficiency13.1.3 How design contributes to API efficiency13.2 Optimizing the design only when necessary13.2.1 Ensuring HTTP configuration efficiency13.2.2 Limiting API usage with rate-limiting13.2.3 Enhancing response with rate-limiting headers13.2.4 Finding the true root cause13.3 Focusing on user needs and user-friendliness to be efficient13.3.1 What we’ve learned so far13.3.2 Analyzing an inefficient flow13.3.3 Optimizing each operation13.3.4 Rethinking the flow13.4 Enabling caching and conditional readings13.4.1 An overview of caching and conditional readings13.4.2 Not letting consumers decide how to cache13.4.3 Defining caching policies based on data and context13.4.4 Returning cache directives13.4.5 Retrieving data only when modified13.5 Optimizing data volume13.5.1 Enabling resource model selection13.5.2 Toggling the return of updated or created resources13.5.3 Enabling field selection13.5.4 Centralizing redundant data in dedicated operations13.5.5 Considering a partial update over total replacement13.5.6 Contrasting JSON Merge Patch and JSON Patch for array updates13.6 Optimizing pagination13.6.1 Optimizing page size limits13.6.2 Choosing cursor- or index-based pagination13.7 Processing multiple elements with bulk or batch operations13.7.1 Designing bulk operation requests13.7.2 Optimizing bulk operation requests13.7.3 Clarifying a bulk operation error policy13.7.4 Designing a mixed response13.7.5 Designing an all-or-nothing response13.7.6 Optimizing bulk request responses13.7.7 Partitioning access to bulk operations13.8 Considering a separate optimized API
14 Adapting the API design to the context
14.1 Integrating context into the API design14.1.1 How context can affect the design of an API14.1.2 Seeking constraints and limitations during design14.1.3 Challenging constraints and limitations14.1.4 Making trade-offs14.2 Dealing with consumer and provider constraints14.2.1 Working around consumer HTTP method limitations14.2.2 Accommodating consumers who are used to different data formats14.2.3 Managing planned interruptions14.2.4 Ensuring data and URL compatibility14.2.5 Implementing partial updates14.3 Handling data and files14.3.1 Collecting data and files in a flow14.3.2 Sending data and files with a single call14.3.3 Retrieving data and files with a single call14.3.4 Describing files with OpenAPI14.3.5 Describing mixed data and files with OpenAPI14.4 Providing efficient file management features14.4.1 Returning file data only when necessary14.4.2 Enabling partial downloads and uploads14.4.3 Preventing unnecessary uploads14.5 Delegating file downloads and uploads14.5.1 Downloading files from another system14.5.2 Uploading files to another system14.6 Notifying consumers about provider-sourced events with a webhook14.6.1 What is a webhook, and why should we consider using one?14.6.2 Webhooks should be optional14.6.3 Designing a webhook operation14.6.4 Using a standard event format14.6.5 Choosing event data granularity14.6.6 Designing a secure webhook14.6.7 Defining the expected webhook behavior14.6.8 Dealing with webhook failures14.6.9 Describing a webhook with OpenAPI14.7 Handling long operations14.7.1 Starting a long operation and monitoring its status with polling14.7.2 Using a callback API to avoid polling14.7.3 Describing a callback with OpenAPI14.7.4 Choosing an execution mode with the Prefer header14.8 Considering other API types14.8.1 Introducing REST API alternatives14.8.2 When to select an API type
15 Modifying an API
15.1 An overview of API modification concerns15.1.1 What can happen when modifying an API?15.1.2 Uncovering API design modification concerns15.1.3 How to design API modifications15.2 Identifying breaking changes and ensuring backward compatibility15.2.1 Modifying output data15.2.2 Modifying input data15.2.3 Modifying resource paths15.2.4 Modifying operations or their HTTP methods15.2.5 Modifying HTTP statuses15.2.6 Modifying operation flows15.2.7 Being aware of the invisible contract15.2.8 Preventing unintended modifications15.3 Identifying security-breaking changes and preventing breaches15.4 Assigning a version to an API15.4.1 Differentiating interface and implementation versioning15.4.2 Choosing an API version identifier15.4.3 How the API version can be represented in a request15.4.4 Choosing how to represent the API version in a request15.4.5 When to choose an API version scheme and representation15.4.6 Avoiding sub-API-level versioning15.5 Carefully breaking and versioning an API15.5.1 Listing consumers and their types15.5.2 Checking whether consumers use what we break15.5.3 Determining whether it’s possible to expose multiple API versions15.5.4 Complying with the API versioning policy15.5.5 Balancing effects and benefits of breaking changes15.5.6 Accumulating trade-offs or breaking regularly15.6 Creating extensible API designs15.6.1 Designing a user-friendly, interoperable REST API that does the job15.6.2 Learning from past decisions15.6.3 Using extensible design patterns15.6.4 Providing deprecation runtime information15.7 Describing the design modifications with OpenAPI15.7.1 Indicating the API version15.7.2 Deprecating elements15.7.3 Adding a changelog
Part 4 Scaled and simplified API design
16 Facilitating API design decision-making
16.1 Making design decisions confidently and consistently16.1.1 Ensuring that it’s the right time to make a decision16.1.2 Evaluating the scope of the decision16.1.3 Deciding based on trusted past decisions16.1.4 Deciding based on trusted external sources16.1.5 Backing decisions with reasoning and sourced information16.1.6 Explaining out loud16.2 Researching solutions to API design questions16.2.1 Where to research solutions to design questions16.2.2 Searching and considering16.2.3 Using an architectural decision record format16.3 What are API design guidelines?16.3.1 How design guidelines can help us16.3.2 How API design guidelines relate to API governance16.3.3 When do we need design guidelines?16.4 What to put in user-friendly API design guidelines16.4.1 Listing principles and rules16.4.2 Providing actionable recipes16.4.3 Providing ready-to-use artifacts and tools16.4.4 Helping with the API design process16.4.5 Adding implementation or architecture considerations16.5 How to build API design guidelines16.5.1 Starting with basic API design guidelines16.5.2 Considering existing APIs16.5.3 Expanding the guidelines when new questions arise16.5.4 Ensuring that each rule brings value16.5.5 Carefully modifying API design guidelines
17 Optimizing an OpenAPI document
17.1 An overview of OpenAPI document optimization17.2 Defining consistent data models17.2.1 Reusing schemas17.2.2 Defining subschemas17.2.3 Targeting part of a schema with a deep reference17.2.4 Overriding descriptions when using a $ref17.2.5 Creating unique read-and-write models17.2.6 Defining a complete schema from its summary17.2.7 Considering schema optimizations17.3 Defining consistent parameters17.3.1 Using path-level parameters17.3.2 Reusing parameters17.3.3 Defining reusable groups of query parameters17.4 Defining consistent request bodies17.5 Defining consistent responses17.5.1 Reusing response headers17.5.2 Reusing responses17.6 Ensuring cross-API consistency with external shared components17.6.1 Defining a library of reusable components17.6.2 Using a shared component in an API17.6.3 Ensure that library files are editable independently17.7 Enhancing API design guidelines
18 Automating API design guidelines
18.1 What API linting is and how it can help us18.1.1 Detecting API design and OpenAPI authoring problems18.1.2 Applying guidelines seamlessly and concentrating on user needs18.2 Using an API linter to automate API design guidelines18.2.1 Developing linting rules to automate guidelines18.2.2 Using our automated guidelines while designing APIs18.2.3 Choosing an API linter18.3 Introducing Spectral18.3.1 Linting an OpenAPI document with Spectral CLI18.3.2 How Spectral lints an OpenAPI document18.3.3 Editing Spectral rulesets18.4 Deciding what API linting rules verify18.4.1 Using our guidelines to create only needed rules18.4.2 Finding small problems to solve18.4.3 Simplifying rules with shared OpenAPI components18.4.4 Ensuring appropriate granularity with a concise name and description18.5 Targeting elements to check in the OpenAPI documents18.5.1 Starting rule development by targeting the proper elements18.5.2 Targeting any element in the OpenAPI document18.5.3 Dealing with references to local or shared components18.5.4 Creating a library to target typical elements18.6 Checking element values18.6.1 Performing basic checks on values and keys18.6.2 Ensuring that an element is defined18.6.3 Ensuring that an element is not defined18.6.4 Checking references18.6.5 Checking partial JSON schemas18.6.6 Performing cross-element checks18.7 Returning helpful feedback when problems are detected18.7.1 Stating the importance or nature of a problem with a severity18.7.2 Returning problem-solving message18.7.3 Splitting rules due to severity or message concerns18.8 Organizing rules18.9 Using our automated guidelines when designing APIs18.9.1 Importing and tweaking the guidelines ruleset18.9.2 Ignoring certain problems
19 Enriching API design artifacts
19.1 Crafting an API design reference kit19.1.1 What an API design reference kit can contain19.1.2 Using the kit to design the API19.1.3 Using the kit to develop the API19.1.4 Using the kit to test the API19.1.5 Using the kit to deploy the API19.1.6 Using the kit to provide and consume the API19.1.7 What we already have and what we may want to add19.2 Providing an overview of the API design with OpenAPI19.2.1 Adding links to other artifacts and describing the API19.2.2 Organizing operations around concepts and use cases19.2.3 Describing use cases19.3 Enhancing the precision of data models with JSON Schema19.3.1 Describing a number or element size range19.3.2 Describing a value with pattern, enum, and default19.4 Providing examples to illustrate data and operations19.4.1 Adding property examples with JSON Schema19.4.2 Adding examples of parameters, request and response bodies, and headers with OpenAPI19.4.3 Authoring accurate and realistic examples19.4.4 Sharing OpenAPI examples across operations19.4.5 Connecting examples to each other19.5 Enhancing and adapting artifacts for implementers19.5.1 Embedding implementation notes in artifacts19.5.2 Enhancing or adapting OpenAPI for code generation19.6 Considering API mocking or prototyping during API design19.6.1 Creating a basic mock with OpenAPI19.6.2 Favoring an early prototype over a complex mock during design19.7 Considering creating functional API tests during API design19.7.1 Clarifying logic19.7.2 Smoothing collaboration19.7.3 Designing standard APIs
appendix A. Solutions to the exercises

Overview

Learn how to design web APIs that are a delight to use and maintain.

Thousands of developers have followed renowned API expert Arnaud Lauret’s guidance to create APIs that are flexible, secure, and easily integrated. This new edition of the bestselling The Design of Web APIs covers the latest updates to the OpenAPI standard, teaches you to streamline and standardize API design decisions with rationale and automation, and gives you insights you can apply to other API styles, such as gRPC. You’ll quickly see how a well-designed and properly-documented API gives your users autonomy—and saves you from constant explanations and hand-holding.

This fully revised second edition of The Design of Web APIs teaches you the principles and techniques you need to design easy-to-consume public and private web APIs. In it, you’ll learn how to:

Analyze requirements to identify API capabilities for versatile, reusable designs
Create HTTP-based REST APIs with CRUD, batch/bulk, or long operations
Design interoperable, user-friendly APIs with seamless operations and data flow
Ensure secure, efficient APIs while overcoming limitations and constraints
Modify APIs without breaking compatibility, evaluating consequences carefully
Future-proof your APIs and choose effective versioning strategies
Document REST APIs using OpenAPI and JSON Schema for seamless implementation
Streamline and standardize API design decisions with rationale and automation

The Design of Web APIs, Second Edition teaches vital skills for gathering requirements, balancing business and technical goals and constraints, and adopting a consumer-first mindset. Each chapter is packed full of hands-on examples, including designing an Online Shopping API and user-friendly banking operations, and over seventy exercises to help your new skills stick. Plus, you’ll explore paradigms applicable beyond REST APIs, and fully describe and document your APIs with OpenAPI and JSON Schema. Your web APIs will soon be easier to consume and your clients—internal and external—will be happier than ever!

About the Technology
Web APIs open up your software to developers, exposing features, and capabilities to other programs. Well-designed web APIs are a joy. The bad ones are a nightmare, with endless impact on system performance, developer productivity, and end-user experience. This book shows you how to design APIs your fellow developers will love to use.

About the Book
The Design of Web APIs, Second Edition teaches you to design efficient and adaptable REST APIs. This revised and rewritten second edition contains the latest updates to the OpenAPI standard, along with insights you can apply to other API styles such as GraphQL. Learn vital skills for gathering requirements, creating easy-to-consume public and private web APIs, and handling non-backward compatible modifications and versioning.

What's Inside

Design reusable, user-friendly and interoperable APIs
Document your APIs with OpenAPI and JSON Schema
Create secure and efficient APIs by design
Streamline and standardize API design decisions

About the Reader
Written for developers with experience building and consuming APIs.

About the Author
Arnaud Lauret runs the API Handyman blog and is a frequent speaker at API conferences. He currently works as an API Industry Researcher at Postman.

Quotes
Brings together excellent knowledge, experience, and practices. Two thumbs up!
- Mike Amundsen, Amundsen.com, Inc

Distills API design into a clear and understandable approach that will stand the test of time.
- James Higginbotham, APICoach.io

You need this book on your bookshelf! Clear, informative, and practical.
- Lorna Mitchell, OpenAPI Initiative

Design APIs with confidence! Arnaud’s approach is both easy to follow and instantly applicable.
- Joyce Stack, Elsevier

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Publisher Resources

ISBN: 9781633438149Publisher Support Publisher Website

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills