Home Page Icon
Home Page
Table of Contents for
Lists of Figures, Tables and Listings
Close
Lists of Figures, Tables and Listings
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
Index
Next
Next Chapter
Cover
Lists of Figures, Tables and Listings
List of Illustrations
Figure 1.1: Three different types of APIs
Figure 1.2: Comparing an application’s user interface (UI) to an application programming interface (API)
Figure 1.3: Web APIs are remote APIs that can be used with the HTTP protocol.
Figure 1.4: A system composed of public and private software LEGO® bricks connected via APIs.
Figure 1.5: The parallels between dining at a restaurant and using an API
Figure 1.6: The cryptic interface of the UDRC 1138 device
Figure 1.7: The UDRC 1138’s documentation
Figure 2.1: The Kitchen Radar 3000
Figure 2.2: The Kitchen Radar 3000’s (insane) user manual
Figure 2.3: Rebranding the Kitchen Radar 3000 as a microwave oven
Figure 2.4: Simplifying use by redesigning the control panel
Figure 2.5: Comparing a microwave oven to software
Figure 2.6: The consumer’s versus provider’s perspective
Figure 2.7: How we redesigned the Kitchen Radar 3000’s control panel
Figure 2.8: The Shopping API whats and hows
Figure 2.9: The whats, the hows, and their inputs and outputs
Figure 2.10: Adding a missing how
Figure 2.11: Adding a missing what
Figure 2.12: Shopping API goals list with the new user’s manage their orders what
Figure 2.13: Investigating the whos, whats, hows, inputs, and outputs to identify goals
Figure 2.14: The API goals canvas
Figure 2.15: The Shopping API goals canvas (partial view)
Figure 2.16: The different facets of the provider’s perspective
Figure 2.17: Exposing the data organization through the API
Figure 2.18: Fixing data organization exposure
Figure 2.19: Exposing business logic through the API
Figure 2.20: Fixing business logic exposure
Figure 2.21: Exposing software architecture through the API
Figure 2.22: Fixing software architecture exposure
Figure 2.23: Avoiding human organization exposure
Figure 2.24: The updated API goals canvas
Figure 3.1: REST programming interface for the get product goal
Figure 3.2: A REST API call using the HTTP protocol
Figure 3.3: The basic structure of an HTTP request and response
Figure 3.4: Mapping a goal to an HTTP request
Figure 3.5: From goals to REST API
Figure 3.6: The API goals canvas for the manage catalog what
Figure 3.7: Identifying resources
Figure 3.8: Identifying resource relationships
Figure 3.9: Identifying actions
Figure 3.10: Identifying action parameters and returns
Figure 3.11: All the identified resources and actions
Figure 3.12: A REST resource’s path. The only requirement is that it must be unique, but it should also be explicit.
Figure 3.13: A REST resource’s path should expose hierarchy and type.
Figure 3.14: Choosing your resource path format
Figure 3.15: Add product to catalog as an HTTP request
Figure 3.16: Search for products in catalog using a free query as an HTTP request
Figure 3.17: Get product as an HTTP request
Figure 3.18: Delete product as an HTTP request
Figure 3.19: Update product as an HTTP request
Figure 3.20: Replace product as an HTTP request
Figure 3.21: REST API and HTTP cheat sheet
Figure 3.22: Designing API data
Figure 3.23: Designing a consumer-oriented concept
Figure 3.24: Property characteristics
Figure 3.25: The product’s resource properties
Figure 3.26: Different representations of the same concept in different response contexts
Figure 3.27: Designing different responses from a single concept
Figure 3.28: Different representations of the same concept in different parameter contexts
Figure 3.29: Designing different parameters from a single concept
Figure 3.30: Verifying that consumers can provide all the parameter’s data
Figure 3.31: Using an action resource
Figure 3.32: Updating a status
Figure 3.33: Conforming to the REST API model
Figure 3.34: A balance between user-friendliness and API type compliance
Figure 3.35: A distributed system
Figure 3.36: REST constraints and the consumer perspective
Figure 3.37: Creating APIs with uniform interfaces using HTTP
Figure 4.1: Describing a programming interface with an API description format
Figure 4.2: An OAS document describing the search for products goal of the Shopping API
Figure 4.3: The Swagger Editor, an online OAS editor
Figure 4.4: An OAS document rendered in ReDoc
Figure 4.5: When to use an API description format
Figure 4.6: From figure to OAS document
Figure 4.7: Adding a resource to the OAS document
Figure 4.8: Adding an action to a resource
Figure 4.9: Adding another action to a resource
Figure 4.10: OAS document corresponding to the initial figure
Figure 4.11: From figures and tables to a detailed OAS document
Figure 4.12: The search for products free query parameter
Figure 4.13: A basic product description
Figure 4.14: A product description with required flags
Figure 4.15: A product with supplier description
Figure 4.16: Describing the search for products response
Figure 4.17: Describing the add product body parameter
Figure 4.18: Reusable components in the OAS document
Figure 4.19: JSON references to local components
Figure 4.20: The product resource and its actions
Figure 5.1: A terrible interface that does the job
Figure 5.2: Transforming an alarm clock into a less usable device
Figure 5.3: Choosing a property name
Figure 5.4: Impacts of data types and format on usability
Figure 5.5: Simplify consumers work with ready-to-use data
Figure 5.6: Straightforward versus tricky washing machine
Figure 5.7: Designing straightforward inputs
Figure 5.8: Malformed request and functional errors
Figure 5.9: Choosing accurate HTTP status codes
Figure 5.10: Handling different types of errors
Figure 5.11: Fully informative success feedback
Figure 5.12: Improving elevator usage flows
Figure 5.13: The Banking API goals canvas
Figure 5.14: The transfer money flow
Figure 5.15: Preventing errors in the money transfer flow
Figure 5.16: A single call is needed to list destinations from the selected source.
Figure 5.17: A single call provides all the data needed to select the source and destination.
Figure 6.1: A washing machine and cassette player sharing the same icon
Figure 6.2: Inconsistent and consistent naming
Figure 6.3: Inconsistent and consistent data types and formats
Figure 6.4: Inconsistent organization
Figure 6.5: Play and pause symbols defined by the ISO 7000 standard
Figure 6.6: A common URL pattern
Figure 6.7: A list of transactions as JSON and CSV
Figure 6.8: Two options to request the transactions list as a CSV document
Figure 6.9: Requesting three different representations of an account’s transactions list
Figure 6.10: Negotiating content language with an API
Figure 6.11: Simple pagination
Figure 6.12: Providing metadata to explain “Where am I and what can I do”
Figure 6.13: Hypermedia Banking API
Figure 7.1: The organization of a TV remote control’s buttons affects its usability.
Figure 7.2: Grouping data in the bank account’s representation
Figure 7.3: Sorting data in the bank account’s representation
Figure 7.4: Grouping data to manage an optional group of required properties
Figure 7.5: Grouped and sorted errors
Figure 7.6: Grouping goals with tags in an OpenAPI Specification document
Figure 7.7: Grouping goals with tags based on functionality versus URL representation
Figure 7.8: Sorting goal groups by adding sorted tags definitions
Figure 7.9: Sorting goals in the OpenAPI Specification document
Figure 7.10: Grouping resources by paths
Figure 7.11: How would you organize these goals?
Figure 7.12: The not-so-handy (and kind of gross) Bathroom Buddy, which does too many things
Figure 7.13: Number of properties and maximum depth of a bank account representation
Figure 7.14: Choosing the number of properties and maximum depth
Figure 7.15: Different goal granularity when reading and modifying data
Figure 7.16: From one Banking API to separate Bank Account and Money Transfer APIs
Figure 8.1: Zooming in on an API call from the security perspective
Figure 8.2: Registering a consumer to select which part of the API will be used and to get credentials
Figure 8.3: Roles involved in the OAuth 2.0 implicit flow
Figure 8.4: Authenticating the Awesome Banking Application and its end users, which provides an access token allowing them to consume the Banking API
Figure 8.5: The Awesome Banking Application requests to list accounts.
Figure 8.6: How API security and API collide
Figure 8.7: Different consumers with different needs do not use the same goals.
Figure 8.8: Controlling access with fine-grained, goal-based scopes
Figure 8.9: Defining fine-grained scopes based on concepts and actions
Figure 8.10: Defining category-based scopes is usually not a good idea.
Figure 8.11: Defining role- and functionality-based scopes
Figure 8.12: The same goals can belong to different scopes.
Figure 8.13: Two seemingly identical requests giving different results
Figure 8.14: The API goals canvas
Figure 8.15: Designing a secure representation of a banking card
Figure 8.16: Adapting representations of sensitive data to make it non-sensitive
Figure 8.17: Controlling access to goals exposing sensitive data
Figure 8.18: A not-so-secure connection between consumer and provider
Figure 9.1: A consumer encountering a breaking change after updating the Banking API
Figure 9.2: How to introduce breaking changes in the list transactions goal’s output
Figure 9.3: Designing backward-compatible modifications to the output data
Figure 9.4: How to introduce breaking changes in the transfer money goal’s input data
Figure 9.5: Designing backward-compatible modifications to the input data
Figure 9.6: Introducing breaking changes in error feedback
Figure 9.7: Modifying HTTP status codes
Figure 9.8: Introducing security breaches and breaking changes when modifying scopes
Figure 9.9: The Banking Company has updated its Banking API to version 2.
Figure 9.10: The evolution of the Banking API and its implementation
Figure 9.11: Various ways of indicating the version of an API in a request
Figure 9.12: API versioning versus resource versioning
Figure 9.13: API versioning versus goal (or operation) versioning
Figure 9.14: Data (or message) versioning with content negotiation
Figure 9.15: Choosing extensible data envelopes
Figure 9.16: Choosing types wisely and using self-descriptive data
Figure 9.17: Grouping similar data in a list
Figure 9.18: Using standards and a wider range of self-descriptive values
Figure 10.1: Network concerns influence API design
Figure 10.2: The Banking API
Figure 10.3: The Awesome Banking App consumes the Banking API’s goals.
Figure 10.5: Decomposing an API call made over a mobile network
Figure 10.6: A basic use case with a user who has access to a single account owner who owns a single account
Figure 10.7: A complex use case with a user who has access to four owners and their eight accounts
Figure 10.8: An average navigation through the Awesome Banking App
Figure 10.9: Reducing the number of calls with caching
Figure 10.10: Using the HTTP protocol’s caching features
Figure 10.11: The Banking API goals
Figure 10.12: Cursor-based pagination to retrieve transactions
Figure 10.13: Choosing relevant summarized representations in lists
Figure 10.14: Using full representations in lists
Figure 10.15: Aggregating subresources and the parent resource
Figure 10.16: Extended aggregation has an impact on communication.
Figure 10.17: Using content negotiation to get an appropriate representation
Figure 10.18: Expanding the owner’s accounts subresource in the owners list
Figure 11.1: Provider and consumer contexts influence API design.
Figure 11.2: A money transfer requiring human validation
Figure 11.3: Using a webhook to notify the consumer of the execution of a money transfer
Figure 11.4: How the Banking API could provide stock information
Figure 11.5: Streaming events to consumers with HTTP SSE
Figure 11.6: Checking multiple transactions in one call
Figure 11.7: Contrasting multiple responses to the update transaction goal with a single response to the update transactions goal
Figure 11.8: Adapting design to what consumers are used to
Figure 11.9: Provider’s limitation examples
Figure 11.10: Contrasting resource-, data- and function-based APIs
Figure 12.1: Different types of documentation
Figure 12.2: Reference documentation generated from an OpenAPI Specification file using the ReDoc open source tool
Figure 12.3: Data model reference documentation
Figure 12.4: Data model reference example
Figure 12.5: An overview of the transfer money goal
Figure 12.6: Multiple goal input examples
Figure 12.7: Goal outputs
Figure 12.8: Multiple goal output examples
Figure 12.9: Goal organization
Figure 12.10: How the Banking API is secured and what the available scopes are
Figure 12.11: Which scopes are needed to create a money transfer
Figure 12.12: An API’s short description and contact information in the reference documentation
Figure 12.13: An API user guide
Figure 12.14: An excerpt of the API goals canvas made while designing the Banking API.
Figure 12.15: API description with enhanced description and implementation information
Figure 12.16: A simple change log listing modifications made in each version
Figure 12.17: Indicating deprecated elements using the OpenAPI Specification file
Figure 13.1: The API lifecycle
Figure 13.2: The Banking Company’s API design principles
Figure 13.3: A use case description in the Banking Company’s API design guidelines
Figure 13.4: The Banking Company’s How to Design APIs page in the design guidelines
Figure 13.5: The Banking Company’s Implementation considerations page in the design guidelines
Figure 13.6: Challenging needs checklist
Figure 13.7: An example API linting checklist
Figure 13.8: Checking the design from the provider’s perspective
Figure 13.9: Checking the design from the consumer’s perspective
List of Tables
Table 5.1 Malformed request and functional error HTTP status codes
Table 7.1 HTTP status code examples
Table 7.2 How would you organize and split this Shopping API goals list?
Table 8.1 Error feedback use cases
Table 9.1 Breaking changes to output data and their consequences
Table 9.2 Breaking changes to input data and their consequences
Table 9.3 Choosing a versioning granularity for REST APIs
List of Listings
Listing 2.1: Using the Kitchen Radar 3000 API
Listing 2.2: Fixing the bug
Listing 2.3: Using the Microwave Oven API
Listing 3.1: Query parameter examples
Listing 4.1: A minimal but valid OAS document
Listing 4.2: Describing a resource
Listing 4.3: Describing an action on a resource
Listing 4.4: Describing an action’s responses
Listing 4.5: Describing another action
Listing 4.6: Describing parameters
Listing 4.7: Describing a query parameter
Listing 4.8: Describing a very basic product with JSON Schema
Listing 4.9: Required and optional properties for product
Listing 4.10: Documenting a JSON schema
Listing 4.11: Describing a complex property with the JSON Schema
Listing 4.12: Describing the response’s data
Listing 4.13: Describing an array of products
Listing 4.14: Array of products JSON example
Listing 4.15: Describing an action’s body parameter
Listing 4.16: Body parameter’s complete description
Listing 4.17: Product information JSON example
Listing 4.18: Declaring a reusable schema
Listing 4.19: Using a predefined component with its reference
Listing 4.20: Using a predefined component in an array with its reference
Listing 4.21: Deleting a product
Listing 4.22: Describing a reusable parameter
Listing 4.23: Using a predefined parameter
Listing 4.24: Resource-level parameters
Listing 5.1: A basic error response body
Listing 5.2: A detailed error response
Listing 5.3: A detailed error response using a generic type
Listing 5.4: A detailed error response indicating an error source
Listing 5.5: Returning multiple errors
Listing 6.1: A bank account as a HAL document
Listing 6.2: A money transfer as a Siren document
Listing 6.3: Using the OPTIONS HTTP method
Listing 6.4: A response indicating other available formats with the Link header
Listing 8.1: Describing scopes
Listing 8.2: Linking a goal to scopes
Listing 8.3: Grouping scopes
Listing 8.4: Linking a goal to scopes from different groups
Listing 9.1: Activating a redirects flag on a Java
HttpUrlConnection
Listing 9.2: An informative error message
Listing 10.1: A GraphQL API call and its response
Listing 10.2: Retrieving some owner and account data
Listing 10.3: Executing multiple queries
Listing 10.4: Adding an updated balance to transactions
Listing 11.1: The complete SSE specification
Listing 11.2: The JSON schema of the update transaction goal’s body
Listing 11.3: The JSON schema of the update transactions goal’s body
Listing 11.4: A
207 Multi-Status
response as described in RFC 4918
Listing 11.5: The multi-status response’s JSON Schema
Listing 11.6: An example generated using the JSON Schema
Listing 11.7: An ISO 20022 IdentificationVerificationRequestV02 XML message
Listing 11.8: An ISO 20022 IdentificationVerificationReportV02 XML message
Listing 11.9: A GraphQL query
Listing 11.10: A GraphQL response with an error
Listing 12.1: A very complete description of a property with an example
Listing 12.2: Documentation tools rely on descriptions to generate examples
Listing 12.3: The transfer money goal’s basic reference documentation
Listing 12.4: The transfer money goal overview’s OpenAPI Specification file
Listing 12.5: Multiple examples of the transfer money goal’s request body
Listing 12.6: A detailed error description
Listing 12.7: Describing tags
Listing 12.8: Defining API security and attaching scopes to a goal
Listing 12.9: The
info
section of the underlying OpenAPI Specification file
Listing 12.10: How ReDoc takes advantage of the OpenAPI Specification file
Listing 12.11: Adding custom properties into an OpenAPI Specification file
Listing 12.12: Security controls information on the get account goal
Listing 12.13: Deprecating the List money transfers for admins goal
Listing 12.14: Deprecating the
t
query parameter
Listing 12.15: A response with a
Sunset
header
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