The Design of Web APIs
Arnaud Lauret
  • MEAP began February 2018
  • Publication in Fall 2019 (estimated)
  • ISBN 9781617295102
  • 400 pages (estimated)
  • printed in black & white

Great book, it's a journey from novice to professional for developing Web APIs that are robust, friendly and easy to consume.

Mohammad Ali Bazzi
Web APIs are everywhere, giving developers an efficient way to interact with applications, services, and data. Well-designed APIs are a joy to use; poorly-designed APIs are cumbersome, confusing, and frustrating. The Design of Web APIs is a practical, example packed guide to crafting extraordinary web APIs. Author Arnaud Lauret demonstrates fantastic design principles and techniques you can apply to both public and private web APIs.
Table of Contents detailed table of contents

Part 1: API Design Fundamentals

1 What is API design?

1.1 What is an API?

1.1.1 An API is a web interface for software

1.1.2 APIs turn software into LEGO® bricks

1.2 Why API design matters

1.2.1 A public or private API is an interface for other developers

1.2.2 An API is made to hide the implementation

1.2.3 The terrible consequences of poorly designed APIs

1.3 The elements of API design

1.3.1 Learning the principles beyond programming interface design

1.3.2 Exploring all facets of API design

1.4 Summary

2 Designing an API for its users

2.1 The right perspective for designing everyday user interfaces

2.1.1 Focusing on how things work leads to complicated interfaces

2.1.2 Focusing on what users can do leads to simple interfaces

2.2 Designing software’s interfaces

2.2.1 Viewing an API as software’s control panel

2.2.2 Focusing on the consumer’s perspective to create simple APIs

2.3 Identifying an API’s goals

2.3.1 Identifying the whats and the hows

2.3.2 Identifying inputs and outputs

2.3.3 Identifying missing goals

2.3.4 Identifying all users

2.3.5 Using the API goals canvas

2.4 Avoiding the provider’s perspective when designing APIs

2.4.1 Avoiding data influence

2.4.2 Avoiding code and business logic influence

2.4.3 Avoiding software architecture influence

2.4.4 Avoiding human organization influence

2.4.5 Detecting the provider’s perspective in the API goals canvas

2.5 Summary

3 Designing a programming interface

3.1 Introducing REST APIs

3.1.1 Analyzing a REST API call

3.1.2 Basic principles of HTTP

3.1.3 Basic principles of REST APIs

3.2 Transposing API goals into a REST API

3.2.1 Identifying resources and their relations with the API goals canvas

3.2.2 Identifying actions and their parameters and returns with the API goals canvas

3.2.3 Representing resources with paths

3.2.4 Representing actions with HTTP

3.2.5 REST API and HTTP cheat sheet

3.3 Designing the API’s data

3.3.1 Designing concepts

3.3.2 Designing responses from concepts

3.3.3 Designing parameters from concepts or responses

3.3.4 Checking parameter data sources

3.3.5 Designing other parameters

3.4 Striking a balance when facing design challenges

3.4.1 REST trade-off examples

3.4.2 A balance between user-friendliness and compliance

3.5 Understanding why REST matters for the design of any API

3.5.1 Introducing the REST architectural style

3.5.2 The impact of REST constraints on API design

3.6 Summary

4 Describing an API with an API description format

4.1 What is an API description format?

4.1.1 Introducing the OpenAPI Specification

4.1.2 Why use an API description format?

4.1.3 When to use an API description format

4.2 Describing API resources and actions with OAS

4.2.1 Creating an OAS document

4.2.2 Describing a resource

4.2.3 Describing operations on a resource

4.3 Describing API data with OpenAPI and JSON Schema

4.3.1 Describing query parameters

4.3.2 Describing data with JSON Schema

4.3.3 Describing responses

4.3.4 Describing body parameters

4.4 Describing an API efficiently with OAS

4.4.1 Reusing components

4.4.2 Describing path parameters

4.5 Summary

Part 2: Usability

5 Designing a straightforward API

5.1 Designing straightforward representations

5.1.1 Choosing crystal clear names

5.1.2 Choosing ready to use data types and formats

5.1.3 Choosing ready to use data

5.1.4 Designing straightforward representations rules

5.2 Designing straightforward interactions

5.2.1 Requesting straightforward inputs

5.2.2 Identifying all possible error feedback

5.2.3 Returning informative error feedback

5.2.4 Returning exhaustive error feedback

5.2.5 Returning informative success feedback

5.2.6 Designing straightforward interactions rules

5.3 Designing straightforward flows

5.3.1 Building a straightforward goals chain

5.3.2 Preventing errors

5.3.3 Aggregating goals

5.3.4 Design straightforward flows rules

5.4 Summary

6 Designing a predictable API

6.1 Being consistent

6.1.1 Being consistent within an API

6.1.2 Being consistent across APIs

6.1.3 Using and meeting standards

6.1.4 Following common practices and copying others

6.1.5 Finding balance between consistency and simplicity

6.2 Being adaptable

6.2.1 Providing and accepting different formats

6.2.2 Internationalizing and Localizing

6.2.3 Filtering, paginating and sorting

6.3 Being discoverable

6.3.1 Providing metadata

6.3.2 Creating hypermedia APIs

6.3.3 Taking advantage of the (HTTP) protocol

6.4 Summary

7 Designing a concise and well-organized API

7.1 Organizing an API

7.1.1 Organizing data

7.1.2 Organizing feedbacks

7.1.3 Organizing goals

7.2 Sizing an API

7.2.1 Choosing data granularity

7.2.2 Choosing goals granularity

7.2.3 Choosing API granularity

7.3 Summary

Part 3: Designing APIs in context

8 Designing a secure API

8.1 An overview of API security

8.1.1 Registering a consumer

8.1.2 Getting credentials to consume the API

8.1.3 Making an API call

8.1.4 Envisioning API design from the perspective of security

8.2 Partitioning an API to facilitate access control

8.2.1 Defining flexible but complex fine-grained scopes

8.2.2 Defining simple but less flexible coarse-grained scopes

8.2.3 Choosing scope strategies

8.2.4 Defining scopes with the API description format

8.3 Designing from the user’s point of view

8.3.1 Knowing what data is attached to the security layer

8.3.2 Adapting the design when necessary

8.4 Handling sensitive material

8.4.1 Handling sensitive data

8.4.2 Handling sensitive goals

8.4.3 Designing secure error feedback

8.4.4 Identifying architecture and protocol issues

8.5 Summary

9 Evolving an API design

9.1 Designing evolutions of APIs

9.1.1 Avoiding breaking changes in output data

9.1.2 Avoiding breaking changes to input data and parameters

9.1.3 Avoiding breaking changes in success and error feedback

9.1.4 Avoiding breaking changes to goals and flows

9.1.5 Avoiding security breaches and breaking changes

9.1.6 Being aware of the invisible interface contract

9.1.7 Introducing a breaking change is not always a problem

9.2 Versioning an API

9.2.1 Contrasting API and implementation versioning

9.2.2 Choosing an API versioning representation from the consumer’s perspective

9.2.3 Choosing API versioning granularity

9.2.4 Understanding the impacts of API versioning beyond design

9.3 Designing APIs with extensibility in mind

9.3.1 Designing extensible data

9.3.2 Designing extensible interactions

9.3.3 Designing extensible flows

9.3.4 Designing extensible APIs

9.4 Summary

10 Designing a network-efficient API

10.1 Overview of network communication concerns

10.1.1 Setting the scene

10.1.2 Analyzing the problems

10.2 Ensuring network communication efficiency at the protocol level

10.2.1 Activating compression and persistent connections

10.2.2 Enabling caching and conditional requests

10.2.3 Choosing cache policies

10.3 Ensuring network communication efficiency at the design level

10.3.1 Enabling filtering

10.3.2 Choosing relevant data for list representations

10.3.3 Aggregating data

10.3.4 Proposing different representations

10.3.5 Enabling expansion

10.3.6 Enabling querying

10.3.7 Providing more relevant data and goals

10.3.8 Creating different API layers

10.4 Summary

11 Designing in context

11.1 Adapting communication to the goals and nature of the data

11.1.1 Managing long processes

11.1.2 Notifying consumers of events

11.1.3 Streaming flows of events

11.1.4 Processing multiple elements

11.2 Observing the full context

11.2.1 Being aware of consumers' existing practices and limitations

11.2.2 Carefully considering the provider’s limitations

11.3 Choosing an API type according to the context

11.3.1 Contrasting resource-, data-, and function-based APIs

11.3.2 Thinking beyond request/response- and HTTP-based APIs

11.4 Summary

12 Documenting an API

12.1 Creating reference documentation

12.1.1 Documenting data models

12.1.2 Documenting goals

12.1.3 Documenting Security

12.1.4 Providing an overview of the API

12.1.5 Generating documentation from the implementation pros and cons

12.2 Creating a user guide

12.2.1 Documenting use cases

12.2.2 Documenting security

12.2.3 Providing an overview of common behaviors and principles

12.3 Providing adequate information to implementers

12.4 Documenting evolutions and retirement

12.5 Summary

13 Growing APIs

13.1 The API lifecycle

13.2 Building API design guidelines

13.2.1 What to put in API design guidelines

13.2.2 Continuously building guidelines

13.3 Reviewing APIs

13.3.1 Challenging and analyzing needs

13.3.2 Linting the design

13.3.3 Reviewing the design from the provider’s perspective

13.3.4 Reviewing the design from the consumer’s perspective

13.3.5 Verifying the implementation

13.4 Communicating and sharing

13.5 Summary

About the Technology

APIs are programming interfaces that allow applications and services to communicate over a local network or the Internet. Consuming and building APIs is essential for modern applications, whether they are based on SOAP, the current industry standard REST, or even more recent developments like gRPC and GraphQL. Other developers will use your APIs to interact with your software. It’s your job to make sure they’re clearly designed and easy to use.

About the book

The Design of Web APIs introduces you to the challenging and creative world of API design. In this experience-driven guide, you'll learn to think like an API designer, embracing effective practices for requirements gathering, blending business and technical goals, and adopting a consumer-first mindset. You'll master the lifecycle of web API design, including the all-important secure-by-design approach. This book teaches principles that can be applied in any style of API. Most examples are illustrated using REST and the OpenAPI specification.

What's inside

  • Characteristics of a well-designed API
  • Explore the full API design lifecycle
  • Designing user-oriented APIs
  • Secure APIs by design
  • Evolving existing APIs
  • Validating your API designs

About the reader

Written for developers with minimal experience building and consuming APIs.

About the author

Arnaud Lauret is a software architect with 15 years of experience in the banking industry. He has spent a decade using, designing, and building APIs. He’s known on the web as the API Handyman (http://apihandyman.io) and is the creator the API Stylebook (http://apistylebook.com), a collection of resources for API designers.

Manning Early Access Program (MEAP) Read chapters as they are written, get the finished eBook as soon as it’s ready, and receive the pBook long before it's in bookstores.
MEAP combo $44.99 pBook + eBook + liveBook
MEAP eBook $35.99 pdf + ePub + kindle + liveBook

placing your order...

Don't refresh or navigate away from the page.

FREE domestic shipping on three or more pBooks