Home Page Icon
Home Page
Table of Contents for
The Design of Web APIs
Close
The Design of Web APIs
by Arnaud Lauret
The Design of Web APIs
Cover
Titlepage
Copyright
foreword
preface
acknowledgments
about this book
Who should read this book
How this book is organized: a roadmap
About the code
liveBook discussion forum
Other 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 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
Summary
Chapter 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 influences
2.4.2 Avoiding code and business logic influences
2.4.3 Avoiding software architecture influences
2.4.4 Avoiding human organization influences
2.4.5 Detecting the provider’s perspective in the API goals canvas
Summary
Chapter 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 relationships 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 Balancing 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
Summary
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 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
Summary
Part 2: Usable API design
Chapter 5: Designing a straightforward API
5.1 Designing straightforward representations
5.1.1 Choosing crystal-clear names
5.1.2 Choosing easy-to-use data types and formats
5.1.3 Choosing ready-to-use data
5.2 Designing straightforward interactions
5.2.1 Requesting straightforward inputs
5.2.2 Identifying all possible error feedbacks
5.2.3 Returning informative error feedback
5.2.4 Returning exhaustive error feedback
5.2.5 Returning informative success feedback
5.3 Designing straightforward flows
5.3.1 Building a straightforward goal chain
5.3.2 Preventing errors
5.3.3 Aggregating goals
5.3.4 Designing stateless flows
Summary
Chapter 6 : Designing a predictable API
6.1 Being consistent
6.1.1 Designing consistent data
6.1.2 Designing consistent goals
6.1.3 The four levels of consistency
6.1.4 Copying others: Following common practices and meeting standards
6.1.5 Being consistent is hard and must be done wisely
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
Summary
Chapter 7: Designing a concise and well-organized API
7.1 Organizing an API
7.1.1 Organizing data
7.1.2 Organizing feedback
7.1.3 Organizing goals
7.2 Sizing an API
7.2.1 Choosing data granularity
7.2.2 Choosing goal granularity
7.2.3 Choosing API granularity
Summary
Part 3: Contextual API design
Chapter 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 with access control in mind
8.3.1 Knowing what data is needed to control access
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
Summary
Chapter 9: Evolving an API design
9.1 Designing API evolutions
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 impact 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
Summary
Chapter 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
Summary
Chapter 11: Designing an API 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 event flows
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 style 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
Summary
Chapter 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.2.4 Thinking beyond static documentation
12.3 Providing adequate information to implementers
12.4 Documenting evolutions and retirement
Summary
Chapter 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
Summary
Index
Lists of Figures, Tables and Listings
Search in book...
Toggle Font Controls
Playlists
Add To
Create new playlist
Name your new playlist
Playlist description (optional)
Cancel
Create playlist
Sign In
Email address
Password
Forgot Password?
Create account
Login
or
Continue with Facebook
Continue with Google
Sign Up
Full Name
Email address
Confirm Email Address
Password
Login
Create account
or
Continue with Facebook
Continue with Google
Prev
Previous Chapter
The Design of Web APIs
Next
Next Chapter
foreword
contents
Cover
Titlepage
Copyright
contents in brief
contents
foreword
preface
acknowledgments
about this book
Who should read this book
How this book is organized: a roadmap
About the code
liveBook discussion forum
Other 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 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
Summary
Chapter 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 influences
2.4.2 Avoiding code and business logic influences
2.4.3 Avoiding software architecture influences
2.4.4 Avoiding human organization influences
2.4.5 Detecting the provider’s perspective in the API goals canvas
Summary
Chapter 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 relationships 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 Balancing 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
Summary
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 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
Summary
Part 2: Usable API design
Chapter 5: Designing a straightforward API
5.1 Designing straightforward representations
5.1.1 Choosing crystal-clear names
5.1.2 Choosing easy-to-use data types and formats
5.1.3 Choosing ready-to-use data
5.2 Designing straightforward interactions
5.2.1 Requesting straightforward inputs
5.2.2 Identifying all possible error feedbacks
5.2.3 Returning informative error feedback
5.2.4 Returning exhaustive error feedback
5.2.5 Returning informative success feedback
5.3 Designing straightforward flows
5.3.1 Building a straightforward goal chain
5.3.2 Preventing errors
5.3.3 Aggregating goals
5.3.4 Designing stateless flows
Summary
Chapter 6 : Designing a predictable API
6.1 Being consistent
6.1.1 Designing consistent data
6.1.2 Designing consistent goals
6.1.3 The four levels of consistency
6.1.4 Copying others: Following common practices and meeting standards
6.1.5 Being consistent is hard and must be done wisely
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
Summary
Chapter 7: Designing a concise and well-organized API
7.1 Organizing an API
7.1.1 Organizing data
7.1.2 Organizing feedback
7.1.3 Organizing goals
7.2 Sizing an API
7.2.1 Choosing data granularity
7.2.2 Choosing goal granularity
7.2.3 Choosing API granularity
Summary
Part 3: Contextual API design
Chapter 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 with access control in mind
8.3.1 Knowing what data is needed to control access
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
Summary
Chapter 9: Evolving an API design
9.1 Designing API evolutions
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 impact 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
Summary
Chapter 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
Summary
Chapter 11: Designing an API 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 event flows
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 style 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
Summary
Chapter 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.2.4 Thinking beyond static documentation
12.3 Providing adequate information to implementers
12.4 Documenting evolutions and retirement
Summary
Chapter 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
Summary
Index
List of Figures
List of Tables
List of Listings
Guide
Cover
Front Matter
foreword
preface
Part 1: Fundamentals of API design
Chapter 1: What is API design?
Start Reading
Chapter 2: Designing an API for its users
Chapter 3: Designing a programming interface
Chapter 4: Describing an API with an API description format
Part 2: Usable API design
Chapter 5: Designing a straightforward API
Chapter 6 : Designing a predictable API
Chapter 7: Designing a concise and well-organized API
Part 3: Contextual API design
Chapter 8: Designing a secure API
Chapter 9: Evolving an API design
Chapter 10: Designing a network-efficient API
Chapter 11: Designing an API in context
Chapter 12: Documenting an API
Chapter 13: Growing APIs
Pages
Add Highlight
No Comment
..................Content has been hidden....................
You can't read the all page of ebook, please click
here
login for view all page.
Day Mode
Cloud Mode
Night Mode
Reset