The Design of Everyday APIs
Arnaud Lauret
  • MEAP began February 2018
  • Publication in Spring 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 Everyday 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 really is API Design

1.1. What is an API

1.1.1. Everyday APIs

1.1.2. An API is an interface for software

1.1.3. An API is a web interface for software

1.2. What really is an API

1.2.1. An API is also an interface for developers

1.2.2. An API is a screen over complexity

1.2.3. An API is a LEGO® brick connector

1.2.4. API definitions

1.3. Why the design of APIs is so important

1.3.1. More and more public and private APIs

1.3.2. Poor API design has terrible consequences

1.4. What really is learning API design

1.4.1. Learning API design solfeggio

1.4.2. Mastering all aspects of API design

1.5. What we have learned

2. Designing an API for its users

2.1. Designing everyday interfaces

2.1.1. Focusing on how things work is a terrible idea

2.1.2. Focusing on what users can do is a far better idea

2.2. Designing software’s interfaces

2.2.1. An API is a software’s control panel

2.2.2. Consumer’s vs provider’s design perspectives

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. Beware the treacherous provider’s perspective

2.4.1. How data can influence API design

2.4.2. How code and business logic can influence API design

2.4.3. How software architecture can influence API design

2.4.4. How human organization can influence API design

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. Understanding a HTTP request

3.1.2. How a REST API uses the HTTP protocol

3.2. Transposing API goals into a REST API

3.2.1. Identifying resources with the API goals canvas

3.2.2. Identifying actions with the API goals canvas

3.2.3. Representing resources with URLs

3.2.4. Representing actions with HTTP

3.3. Designing 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 parameters data sources

3.3.5. Designing other parameters

3.4. Striking a balance when facing design challenges

3.4.1. REST trade-offs examples

3.4.2. A balance between user-friendliness and compliance

3.5. Introducing the REST architectural style

3.5.1. Discovering the REST architecture style and its constraints

3.5.2. Starting to understand REST constraints impact on API design

3.5.3. Digging into REST beyond this book

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 using an API description format when designing an API

4.1.3. When using an API description format to design API

4.2. Describing API resources and actions with OpenAPI

4.2.1. Initiating an OAS document

4.2.2. Describing a resource

4.2.3. Describing actions on a resource

4.3. Describing all API details 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 efficiently an API with OpenAPI

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: It’s API Designer’s job too

8. Designing a secured API

9. Designing an evolvable API

10. Designing in consumer’s and provider’s contexts

11. Growing an API design

About the Technology

Web 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 Everyday 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 web 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 ( and is the creator of the API Stylebook (, 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.

placing your order...

Don't refresh or navigate away from the page.

FREE domestic shipping on three or more pBooks

The author does a nice job of describing why API design is important whether or not it is used internally or externally.

Louis Aloia

An excellent book for people who desire to master API Design using a consistency approach and a lean and straightforward methodology.

Enrico Mazzarella