book

The Design of Web APIs

Name: The Design of Web APIs
Author: Arnaud Lauret
ISBN: 9781617295102

by Arnaud Lauret

October 2019

Intermediate to advanced

392 pages

11h 46m

English

Manning Publications

Read now

Unlock full access

Cover
Titlepage
Copyright
foreword
preface
acknowledgments
about this book
Who should read this bookHow this book is organized: a roadmapAbout the codeliveBook discussion forumOther online resources
about the author
about the cover illustration
Part 1: Fundamentals of API design

Chapter 1: What is API design?
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
Chapter 2: Designing an API for its users
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
Chapter 3: Designing a programming interface
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
Chapter 4: Describing an API with an API description format
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
Part 2: Usable API design
Chapter 5: Designing a straightforward API
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
Chapter 6 : Designing a predictable API
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
Chapter 7: Designing a concise and well-organized API
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
Part 3: Contextual API design
Chapter 8: Designing a secure API
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
Chapter 9: Evolving an API design
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
Chapter 10: Designing a network-efficient API
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
Chapter 11: Designing an API in context
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
Chapter 12: Documenting an API
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
Chapter 13: Growing APIs
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
Index
Lists of Figures, Tables and Listings

Content preview from The Design of Web APIs

12 Documenting an API

This chapter covers

Reference documentation
User guides
Implementer specifications
Change logs

In previous chapters, you discovered that designing APIs requires more than just designing usable APIs doing the job. Indeed, we have to take care of the whole context surrounding the API when designing it. But this context goes beyond that of the API itself—its interface contract, its implementation, and how and by whom it is used. API designers have to participate in various aspects of API projects, and a very important one is documentation.

The best designs of even the simplest things need documentation. As shown in figure 12.1, everyday objects can come with various types of documentation to help users understand how to use ...

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: 9781617295102Publisher Support Publisher Website

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

The Design of Web APIs

by Arnaud Lauret

12 Documenting an API

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.