The Design of Web APIs

The Design of Web APIs

by Arnaud Lauret
Released October 2019
Publisher(s): Manning Publications
ISBN: 9781617295102

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

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.



About the Technology

An API frees developers to integrate with an application without knowing its code-level details. Whether you’re using established standards like REST and OpenAPI or more recent approaches like GraphQL or gRPC, mastering API design is a superskill. It will make your web-facing services easier to consume and your clients—internal and external—happier.



About the Book

Drawing on author Arnaud Lauret's many years of API design experience, this book teaches you how to gather requirements, how to balance business and technical goals, and how to adopt a consumer-first mindset. It teaches effective practices using numerous interesting examples.



What's Inside

  • Characteristics of a well-designed API
  • User-oriented and real-world APIs
  • Secure APIs by design
  • Evolving, documenting, and reviewing API designs


About the Reader

Written for developers with minimal experience building and consuming APIs.



About the Author

A software architect with extensive experience in the banking industry, Arnaud Lauret has spent 10 years using, designing, and building APIs. He blogs under the name of API Handyman and has created the API Stylebook website.



Quotes
Assembles the fundamental building blocks of API design in an easy-to-access way, and walks you through the vast landscape in a friendly and comfortable manner.
- From the Foreword by Kin Lane, The API Evangelist

Answers nagging and complicated questions with a simple philosophy, but never tries to hide anything from you. A fantastic introduction to the field.
- Bridger Howell, SoFi.com

An excellent guidebook for establishing a path to RESTful APIs.
- Shawn Smith, Penn State University

Combines real-world examples with difficult abstract ideas.
- Shayn Cornwell, XeroOne Systems

Table of contents

  1. Cover
  2. Titlepage
  3. Copyright
  4. foreword
  5. preface
  6. acknowledgments
  7. about this book
    1. Who should read this book
    2. How this book is organized: a roadmap
    3. About the code
    4. liveBook discussion forum
    5. Other online resources
  8. about the author
  9. about the cover illustration
  10. Part 1: Fundamentals of API design
    1. Chapter 1: What is API design?
      1. 1.1 What is an API?
        1. 1.1.1 An API is a web interface for software
        2. 1.1.2 APIs turn software into LEGO® bricks
      2. 1.2 Why API design matters
        1. 1.2.1 A public or private API is an interface for other developers
        2. 1.2.2 An API is made to hide the implementation
        3. 1.2.3 The terrible consequences of poorly designed APIs
      3. 1.3 The elements of API design
        1. 1.3.1 Learning the principles beyond programming interface design
        2. 1.3.2 Exploring all facets of API design
      4. Summary
    2. Chapter 2: Designing an API for its users
      1. 2.1 The right perspective for designing everyday user interfaces
        1. 2.1.1 Focusing on how things work leads to complicated interfaces
        2. 2.1.2 Focusing on what users can do leads to simple interfaces
      2. 2.2 Designing software’s interfaces
        1. 2.2.1 Viewing an API as software’s control panel
        2. 2.2.2 Focusing on the consumer’s perspective to create simple APIs
      3. 2.3 Identifying an API’s goals
        1. 2.3.1 Identifying the whats and the hows
        2. 2.3.2 Identifying inputs and outputs
        3. 2.3.3 Identifying missing goals
        4. 2.3.4 Identifying all users
        5. 2.3.5 Using the API goals canvas
      4. 2.4 Avoiding the provider’s perspective when designing APIs
        1. 2.4.1 Avoiding data influences
        2. 2.4.2 Avoiding code and business logic influences
        3. 2.4.3 Avoiding software architecture influences
        4. 2.4.4 Avoiding human organization influences
        5. 2.4.5 Detecting the provider’s perspective in the API goals canvas
      5. Summary
    3. Chapter 3: Designing a programming interface
      1. 3.1 Introducing REST APIs
        1. 3.1.1 Analyzing a REST API call
        2. 3.1.2 Basic principles of HTTP
        3. 3.1.3 Basic principles of REST APIs
      2. 3.2 Transposing API goals into a REST API
        1. 3.2.1 Identifying resources and their relationships with the API goals canvas
        2. 3.2.2 Identifying actions and their parameters and returns with the API goals canvas
        3. 3.2.3 Representing resources with paths
        4. 3.2.4 Representing actions with HTTP
        5. 3.2.5 REST API and HTTP cheat sheet
      3. 3.3 Designing the API’s data
        1. 3.3.1 Designing concepts
        2. 3.3.2 Designing responses from concepts
        3. 3.3.3 Designing parameters from concepts or responses
        4. 3.3.4 Checking parameter data sources
        5. 3.3.5 Designing other parameters
      4. 3.4 Striking a balance when facing design challenges
        1. 3.4.1 REST trade-off examples
        2. 3.4.2 Balancing user-friendliness and compliance
      5. 3.5 Understanding why REST matters for the design of any API
        1. 3.5.1 Introducing the REST architectural style
        2. 3.5.2 The impact of REST constraints on API design
      6. Summary
    4. Chapter 4: Describing an API with an API description format
      1. 4.1 What is an API description format?
        1. 4.1.1 Introducing the OpenAPI Specification (OAS)
        2. 4.1.2 Why use an API description format?
        3. 4.1.3 When to use an API description format
      2. 4.2 Describing API resources and actions with OAS
        1. 4.2.1 Creating an OAS document
        2. 4.2.2 Describing a resource
        3. 4.2.3 Describing operations on a resource
      3. 4.3 Describing API data with OpenAPI and JSON Schema
        1. 4.3.1 Describing query parameters
        2. 4.3.2 Describing data with JSON Schema
        3. 4.3.3 Describing responses
        4. 4.3.4 Describing body parameters
      4. 4.4 Describing an API efficiently with OAS
        1. 4.4.1 Reusing components
        2. 4.4.2 Describing path parameters
      5. Summary
  11. Part 2: Usable API design
    1. Chapter 5: Designing a straightforward API
      1. 5.1 Designing straightforward representations
        1. 5.1.1 Choosing crystal-clear names
        2. 5.1.2 Choosing easy-to-use data types and formats
        3. 5.1.3 Choosing ready-to-use data
      2. 5.2 Designing straightforward interactions
        1. 5.2.1 Requesting straightforward inputs
        2. 5.2.2 Identifying all possible error feedbacks
        3. 5.2.3 Returning informative error feedback
        4. 5.2.4 Returning exhaustive error feedback
        5. 5.2.5 Returning informative success feedback
      3. 5.3 Designing straightforward flows
        1. 5.3.1 Building a straightforward goal chain
        2. 5.3.2 Preventing errors
        3. 5.3.3 Aggregating goals
        4. 5.3.4 Designing stateless flows
      4. Summary
    2. Chapter 6 : Designing a predictable API
      1. 6.1 Being consistent
        1. 6.1.1 Designing consistent data
        2. 6.1.2 Designing consistent goals
        3. 6.1.3 The four levels of consistency
        4. 6.1.4 Copying others: Following common practices and meeting standards
        5. 6.1.5 Being consistent is hard and must be done wisely
      2. 6.2 Being adaptable
        1. 6.2.1 Providing and accepting different formats
        2. 6.2.2 Internationalizing and localizing
        3. 6.2.3 Filtering, paginating, and sorting
      3. 6.3 Being discoverable
        1. 6.3.1 Providing metadata
        2. 6.3.2 Creating hypermedia APIs
        3. 6.3.3 Taking advantage of the HTTP protocol
      4. Summary
    3. Chapter 7: Designing a concise and well-organized API
      1. 7.1 Organizing an API
        1. 7.1.1 Organizing data
        2. 7.1.2 Organizing feedback
        3. 7.1.3 Organizing goals
      2. 7.2 Sizing an API
        1. 7.2.1 Choosing data granularity
        2. 7.2.2 Choosing goal granularity
        3. 7.2.3 Choosing API granularity
      3. Summary
  12. Part 3: Contextual API design
    1. Chapter 8: Designing a secure API
      1. 8.1 An overview of API security
        1. 8.1.1 Registering a consumer
        2. 8.1.2 Getting credentials to consume the API
        3. 8.1.3 Making an API call
        4. 8.1.4 Envisioning API design from the perspective of security
      2. 8.2 Partitioning an API to facilitate access control
        1. 8.2.1 Defining flexible but complex fine-grained scopes
        2. 8.2.2 Defining simple but less flexible coarse-grained scopes
        3. 8.2.3 Choosing scope strategies
        4. 8.2.4 Defining scopes with the API description format
      3. 8.3 Designing with access control in mind
        1. 8.3.1 Knowing what data is needed to control access
        2. 8.3.2 Adapting the design when necessary
      4. 8.4 Handling sensitive material
        1. 8.4.1 Handling sensitive data
        2. 8.4.2 Handling sensitive goals
        3. 8.4.3 Designing secure error feedback
        4. 8.4.4 Identifying architecture and protocol issues
      5. Summary
    2. Chapter 9: Evolving an API design
      1. 9.1 Designing API evolutions
        1. 9.1.1 Avoiding breaking changes in output data
        2. 9.1.2 Avoiding breaking changes to input data and parameters
        3. 9.1.3 Avoiding breaking changes in success and error feedback
        4. 9.1.4 Avoiding breaking changes to goals and flows
        5. 9.1.5 Avoiding security breaches and breaking changes
        6. 9.1.6 Being aware of the invisible interface contract
        7. 9.1.7 Introducing a breaking change is not always a problem
      2. 9.2 Versioning an API
        1. 9.2.1 Contrasting API and implementation versioning
        2. 9.2.2 Choosing an API versioning representation from the consumer’s perspective
        3. 9.2.3 Choosing API versioning granularity
        4. 9.2.4 Understanding the impact of API versioning beyond design
      3. 9.3 Designing APIs with extensibility in mind
        1. 9.3.1 Designing extensible data
        2. 9.3.2 Designing extensible interactions
        3. 9.3.3 Designing extensible flows
        4. 9.3.4 Designing extensible APIs
      4. Summary
    3. Chapter 10: Designing a network-efficient API
      1. 10.1 Overview of network communication concerns
        1. 10.1.1 Setting the scene
        2. 10.1.2 Analyzing the problems
      2. 10.2 Ensuring network communication efficiency at the protocol level
        1. 10.2.1 Activating compression and persistent connections
        2. 10.2.2 Enabling caching and conditional requests
        3. 10.2.3 Choosing cache policies
      3. 10.3 Ensuring network communication efficiency at the design level
        1. 10.3.1 Enabling filtering
        2. 10.3.2 Choosing relevant data for list representations
        3. 10.3.3 Aggregating data
        4. 10.3.4 Proposing different representations
        5. 10.3.5 Enabling expansion
        6. 10.3.6 Enabling querying
        7. 10.3.7 Providing more relevant data and goals
        8. 10.3.8 Creating different API layers
      4. Summary
    4. Chapter 11: Designing an API in context
      1. 11.1 Adapting communication to the goals and nature of the data
        1. 11.1.1 Managing long processes
        2. 11.1.2 Notifying consumers of events
        3. 11.1.3 Streaming event flows
        4. 11.1.4 Processing multiple elements
      2. 11.2 Observing the full context
        1. 11.2.1 Being aware of consumers' existing practices and limitations
        2. 11.2.2 Carefully considering the provider’s limitations
      3. 11.3 Choosing an API style according to the context
        1. 11.3.1 Contrasting resource-, data-, and function-based APIs
        2. 11.3.2 Thinking beyond request/response- and HTTP-based APIs
      4. Summary
    5. Chapter 12: Documenting an API
      1. 12.1 Creating reference documentation
        1. 12.1.1 Documenting data models
        2. 12.1.2 Documenting goals
        3. 12.1.3 Documenting security
        4. 12.1.4 Providing an overview of the API
        5. 12.1.5 Generating documentation from the implementation: pros and cons
      2. 12.2 Creating a user guide
        1. 12.2.1 Documenting use cases
        2. 12.2.2 Documenting security
        3. 12.2.3 Providing an overview of common behaviors and principles
        4. 12.2.4 Thinking beyond static documentation
      3. 12.3 Providing adequate information to implementers
      4. 12.4 Documenting evolutions and retirement
      5. Summary
    6. Chapter 13: Growing APIs
      1. 13.1 The API lifecycle
      2. 13.2 Building API design guidelines
        1. 13.2.1 What to put in API design guidelines
        2. 13.2.2 Continuously building guidelines
      3. 13.3 Reviewing APIs
        1. 13.3.1 Challenging and analyzing needs
        2. 13.3.2 Linting the design
        3. 13.3.3 Reviewing the design from the provider’s perspective
        4. 13.3.4 Reviewing the design from the consumer’s perspective
        5. 13.3.5 Verifying the implementation
      4. 13.4 Communicating and sharing
      5. Summary
  13. Index
  14. Lists of Figures, Tables and Listings

Product information

  • Title: The Design of Web APIs
  • Author(s): Arnaud Lauret
  • Release date: October 2019
  • Publisher(s): Manning Publications
  • ISBN: 9781617295102