Lists of Figures, Tables and Listings

List of Illustrations

  1. Figure 1.1: Three different types of APIs
  2. Figure 1.2: Comparing an application’s user interface (UI) to an application programming interface (API)
  3. Figure 1.3: Web APIs are remote APIs that can be used with the HTTP protocol.
  4. Figure 1.4: A system composed of public and private software LEGO® bricks connected via APIs.
  5. Figure 1.5: The parallels between dining at a restaurant and using an API
  6. Figure 1.6: The cryptic interface of the UDRC 1138 device
  7. Figure 1.7: The UDRC 1138’s documentation
  8. Figure 2.1: The Kitchen Radar 3000
  9. Figure 2.2: The Kitchen Radar 3000’s (insane) user manual
  10. Figure 2.3: Rebranding the Kitchen Radar 3000 as a microwave oven
  11. Figure 2.4: Simplifying use by redesigning the control panel
  12. Figure 2.5: Comparing a microwave oven to software
  13. Figure 2.6: The consumer’s versus provider’s perspective
  14. Figure 2.7: How we redesigned the Kitchen Radar 3000’s control panel
  15. Figure 2.8: The Shopping API whats and hows
  16. Figure 2.9: The whats, the hows, and their inputs and outputs
  17. Figure 2.10: Adding a missing how
  18. Figure 2.11: Adding a missing what
  19. Figure 2.12: Shopping API goals list with the new user’s manage their orders what
  20. Figure 2.13: Investigating the whos, whats, hows, inputs, and outputs to identify goals
  21. Figure 2.14: The API goals canvas
  22. Figure 2.15: The Shopping API goals canvas (partial view)
  23. Figure 2.16: The different facets of the provider’s perspective
  24. Figure 2.17: Exposing the data organization through the API
  25. Figure 2.18: Fixing data organization exposure
  26. Figure 2.19: Exposing business logic through the API
  27. Figure 2.20: Fixing business logic exposure
  28. Figure 2.21: Exposing software architecture through the API
  29. Figure 2.22: Fixing software architecture exposure
  30. Figure 2.23: Avoiding human organization exposure
  31. Figure 2.24: The updated API goals canvas
  32. Figure 3.1: REST programming interface for the get product goal
  33. Figure 3.2: A REST API call using the HTTP protocol
  34. Figure 3.3: The basic structure of an HTTP request and response
  35. Figure 3.4: Mapping a goal to an HTTP request
  36. Figure 3.5: From goals to REST API
  37. Figure 3.6: The API goals canvas for the manage catalog what
  38. Figure 3.7: Identifying resources
  39. Figure 3.8: Identifying resource relationships
  40. Figure 3.9: Identifying actions
  41. Figure 3.10: Identifying action parameters and returns
  42. Figure 3.11: All the identified resources and actions
  43. Figure 3.12: A REST resource’s path. The only requirement is that it must be unique, but it should also be explicit.
  44. Figure 3.13: A REST resource’s path should expose hierarchy and type.
  45. Figure 3.14: Choosing your resource path format
  46. Figure 3.15: Add product to catalog as an HTTP request
  47. Figure 3.16: Search for products in catalog using a free query as an HTTP request
  48. Figure 3.17: Get product as an HTTP request
  49. Figure 3.18: Delete product as an HTTP request
  50. Figure 3.19: Update product as an HTTP request
  51. Figure 3.20: Replace product as an HTTP request
  52. Figure 3.21: REST API and HTTP cheat sheet
  53. Figure 3.22: Designing API data
  54. Figure 3.23: Designing a consumer-oriented concept
  55. Figure 3.24: Property characteristics
  56. Figure 3.25: The product’s resource properties
  57. Figure 3.26: Different representations of the same concept in different response contexts
  58. Figure 3.27: Designing different responses from a single concept
  59. Figure 3.28: Different representations of the same concept in different parameter contexts
  60. Figure 3.29: Designing different parameters from a single concept
  61. Figure 3.30: Verifying that consumers can provide all the parameter’s data
  62. Figure 3.31: Using an action resource
  63. Figure 3.32: Updating a status
  64. Figure 3.33: Conforming to the REST API model
  65. Figure 3.34: A balance between user-friendliness and API type compliance
  66. Figure 3.35: A distributed system
  67. Figure 3.36: REST constraints and the consumer perspective
  68. Figure 3.37: Creating APIs with uniform interfaces using HTTP
  69. Figure 4.1: Describing a programming interface with an API description format
  70. Figure 4.2: An OAS document describing the search for products goal of the Shopping API
  71. Figure 4.3: The Swagger Editor, an online OAS editor
  72. Figure 4.4: An OAS document rendered in ReDoc
  73. Figure 4.5: When to use an API description format
  74. Figure 4.6: From figure to OAS document
  75. Figure 4.7: Adding a resource to the OAS document
  76. Figure 4.8: Adding an action to a resource
  77. Figure 4.9: Adding another action to a resource
  78. Figure 4.10: OAS document corresponding to the initial figure
  79. Figure 4.11: From figures and tables to a detailed OAS document
  80. Figure 4.12: The search for products free query parameter
  81. Figure 4.13: A basic product description
  82. Figure 4.14: A product description with required flags
  83. Figure 4.15: A product with supplier description
  84. Figure 4.16: Describing the search for products response
  85. Figure 4.17: Describing the add product body parameter
  86. Figure 4.18: Reusable components in the OAS document
  87. Figure 4.19: JSON references to local components
  88. Figure 4.20: The product resource and its actions
  89. Figure 5.1: A terrible interface that does the job
  90. Figure 5.2: Transforming an alarm clock into a less usable device
  91. Figure 5.3: Choosing a property name
  92. Figure 5.4: Impacts of data types and format on usability
  93. Figure 5.5: Simplify consumers work with ready-to-use data
  94. Figure 5.6: Straightforward versus tricky washing machine
  95. Figure 5.7: Designing straightforward inputs
  96. Figure 5.8: Malformed request and functional errors
  97. Figure 5.9: Choosing accurate HTTP status codes
  98. Figure 5.10: Handling different types of errors
  99. Figure 5.11: Fully informative success feedback
  100. Figure 5.12: Improving elevator usage flows
  101. Figure 5.13: The Banking API goals canvas
  102. Figure 5.14: The transfer money flow
  103. Figure 5.15: Preventing errors in the money transfer flow
  104. Figure 5.16: A single call is needed to list destinations from the selected source.
  105. Figure 5.17: A single call provides all the data needed to select the source and destination.
  106. Figure 6.1: A washing machine and cassette player sharing the same icon
  107. Figure 6.2: Inconsistent and consistent naming
  108. Figure 6.3: Inconsistent and consistent data types and formats
  109. Figure 6.4: Inconsistent organization
  110. Figure 6.5: Play and pause symbols defined by the ISO 7000 standard
  111. Figure 6.6: A common URL pattern
  112. Figure 6.7: A list of transactions as JSON and CSV
  113. Figure 6.8: Two options to request the transactions list as a CSV document
  114. Figure 6.9: Requesting three different representations of an account’s transactions list
  115. Figure 6.10: Negotiating content language with an API
  116. Figure 6.11: Simple pagination
  117. Figure 6.12: Providing metadata to explain “Where am I and what can I do”
  118. Figure 6.13: Hypermedia Banking API
  119. Figure 7.1: The organization of a TV remote control’s buttons affects its usability.
  120. Figure 7.2: Grouping data in the bank account’s representation
  121. Figure 7.3: Sorting data in the bank account’s representation
  122. Figure 7.4: Grouping data to manage an optional group of required properties
  123. Figure 7.5: Grouped and sorted errors
  124. Figure 7.6: Grouping goals with tags in an OpenAPI Specification document
  125. Figure 7.7: Grouping goals with tags based on functionality versus URL representation
  126. Figure 7.8: Sorting goal groups by adding sorted tags definitions
  127. Figure 7.9: Sorting goals in the OpenAPI Specification document
  128. Figure 7.10: Grouping resources by paths
  129. Figure 7.11: How would you organize these goals?
  130. Figure 7.12: The not-so-handy (and kind of gross) Bathroom Buddy, which does too many things
  131. Figure 7.13: Number of properties and maximum depth of a bank account representation
  132. Figure 7.14: Choosing the number of properties and maximum depth
  133. Figure 7.15: Different goal granularity when reading and modifying data
  134. Figure 7.16: From one Banking API to separate Bank Account and Money Transfer APIs
  135. Figure 8.1: Zooming in on an API call from the security perspective
  136. Figure 8.2: Registering a consumer to select which part of the API will be used and to get credentials
  137. Figure 8.3: Roles involved in the OAuth 2.0 implicit flow
  138. Figure 8.4: Authenticating the Awesome Banking Application and its end users, which provides an access token allowing them to consume the Banking API
  139. Figure 8.5: The Awesome Banking Application requests to list accounts.
  140. Figure 8.6: How API security and API collide
  141. Figure 8.7: Different consumers with different needs do not use the same goals.
  142. Figure 8.8: Controlling access with fine-grained, goal-based scopes
  143. Figure 8.9: Defining fine-grained scopes based on concepts and actions
  144. Figure 8.10: Defining category-based scopes is usually not a good idea.
  145. Figure 8.11: Defining role- and functionality-based scopes
  146. Figure 8.12: The same goals can belong to different scopes.
  147. Figure 8.13: Two seemingly identical requests giving different results
  148. Figure 8.14: The API goals canvas
  149. Figure 8.15: Designing a secure representation of a banking card
  150. Figure 8.16: Adapting representations of sensitive data to make it non-sensitive
  151. Figure 8.17: Controlling access to goals exposing sensitive data
  152. Figure 8.18: A not-so-secure connection between consumer and provider
  153. Figure 9.1: A consumer encountering a breaking change after updating the Banking API
  154. Figure 9.2: How to introduce breaking changes in the list transactions goal’s output
  155. Figure 9.3: Designing backward-compatible modifications to the output data
  156. Figure 9.4: How to introduce breaking changes in the transfer money goal’s input data
  157. Figure 9.5: Designing backward-compatible modifications to the input data
  158. Figure 9.6: Introducing breaking changes in error feedback
  159. Figure 9.7: Modifying HTTP status codes
  160. Figure 9.8: Introducing security breaches and breaking changes when modifying scopes
  161. Figure 9.9: The Banking Company has updated its Banking API to version 2.
  162. Figure 9.10: The evolution of the Banking API and its implementation
  163. Figure 9.11: Various ways of indicating the version of an API in a request
  164. Figure 9.12: API versioning versus resource versioning
  165. Figure 9.13: API versioning versus goal (or operation) versioning
  166. Figure 9.14: Data (or message) versioning with content negotiation
  167. Figure 9.15: Choosing extensible data envelopes
  168. Figure 9.16: Choosing types wisely and using self-descriptive data
  169. Figure 9.17: Grouping similar data in a list
  170. Figure 9.18: Using standards and a wider range of self-descriptive values
  171. Figure 10.1: Network concerns influence API design
  172. Figure 10.2: The Banking API
  173. Figure 10.3: The Awesome Banking App consumes the Banking API’s goals.
  174. Figure 10.5: Decomposing an API call made over a mobile network
  175. Figure 10.6: A basic use case with a user who has access to a single account owner who owns a single account
  176. Figure 10.7: A complex use case with a user who has access to four owners and their eight accounts
  177. Figure 10.8: An average navigation through the Awesome Banking App
  178. Figure 10.9: Reducing the number of calls with caching
  179. Figure 10.10: Using the HTTP protocol’s caching features
  180. Figure 10.11: The Banking API goals
  181. Figure 10.12: Cursor-based pagination to retrieve transactions
  182. Figure 10.13: Choosing relevant summarized representations in lists
  183. Figure 10.14: Using full representations in lists
  184. Figure 10.15: Aggregating subresources and the parent resource
  185. Figure 10.16: Extended aggregation has an impact on communication.
  186. Figure 10.17: Using content negotiation to get an appropriate representation
  187. Figure 10.18: Expanding the owner’s accounts subresource in the owners list
  188. Figure 11.1: Provider and consumer contexts influence API design.
  189. Figure 11.2: A money transfer requiring human validation
  190. Figure 11.3: Using a webhook to notify the consumer of the execution of a money transfer
  191. Figure 11.4: How the Banking API could provide stock information
  192. Figure 11.5: Streaming events to consumers with HTTP SSE
  193. Figure 11.6: Checking multiple transactions in one call
  194. Figure 11.7: Contrasting multiple responses to the update transaction goal with a single response to the update transactions goal
  195. Figure 11.8: Adapting design to what consumers are used to
  196. Figure 11.9: Provider’s limitation examples
  197. Figure 11.10: Contrasting resource-, data- and function-based APIs
  198. Figure 12.1: Different types of documentation
  199. Figure 12.2: Reference documentation generated from an OpenAPI Specification file using the ReDoc open source tool
  200. Figure 12.3: Data model reference documentation
  201. Figure 12.4: Data model reference example
  202. Figure 12.5: An overview of the transfer money goal
  203. Figure 12.6: Multiple goal input examples
  204. Figure 12.7: Goal outputs
  205. Figure 12.8: Multiple goal output examples
  206. Figure 12.9: Goal organization
  207. Figure 12.10: How the Banking API is secured and what the available scopes are
  208. Figure 12.11: Which scopes are needed to create a money transfer
  209. Figure 12.12: An API’s short description and contact information in the reference documentation
  210. Figure 12.13: An API user guide
  211. Figure 12.14: An excerpt of the API goals canvas made while designing the Banking API.
  212. Figure 12.15: API description with enhanced description and implementation information
  213. Figure 12.16: A simple change log listing modifications made in each version
  214. Figure 12.17: Indicating deprecated elements using the OpenAPI Specification file
  215. Figure 13.1: The API lifecycle
  216. Figure 13.2: The Banking Company’s API design principles
  217. Figure 13.3: A use case description in the Banking Company’s API design guidelines
  218. Figure 13.4: The Banking Company’s How to Design APIs page in the design guidelines
  219. Figure 13.5: The Banking Company’s Implementation considerations page in the design guidelines
  220. Figure 13.6: Challenging needs checklist
  221. Figure 13.7: An example API linting checklist
  222. Figure 13.8: Checking the design from the provider’s perspective
  223. Figure 13.9: Checking the design from the consumer’s perspective

List of Tables

  1. Table 5.1 Malformed request and functional error HTTP status codes
  2. Table 7.1 HTTP status code examples
  3. Table 7.2 How would you organize and split this Shopping API goals list?
  4. Table 8.1 Error feedback use cases
  5. Table 9.1 Breaking changes to output data and their consequences
  6. Table 9.2 Breaking changes to input data and their consequences
  7. Table 9.3 Choosing a versioning granularity for REST APIs

List of Listings

  1. Listing 2.1: Using the Kitchen Radar 3000 API
  2. Listing 2.2: Fixing the bug
  3. Listing 2.3: Using the Microwave Oven API
  4. Listing 3.1: Query parameter examples
  5. Listing 4.1: A minimal but valid OAS document
  6. Listing 4.2: Describing a resource
  7. Listing 4.3: Describing an action on a resource
  8. Listing 4.4: Describing an action’s responses
  9. Listing 4.5: Describing another action
  10. Listing 4.6: Describing parameters
  11. Listing 4.7: Describing a query parameter
  12. Listing 4.8: Describing a very basic product with JSON Schema
  13. Listing 4.9: Required and optional properties for product
  14. Listing 4.10: Documenting a JSON schema
  15. Listing 4.11: Describing a complex property with the JSON Schema
  16. Listing 4.12: Describing the response’s data
  17. Listing 4.13: Describing an array of products
  18. Listing 4.14: Array of products JSON example
  19. Listing 4.15: Describing an action’s body parameter
  20. Listing 4.16: Body parameter’s complete description
  21. Listing 4.17: Product information JSON example
  22. Listing 4.18: Declaring a reusable schema
  23. Listing 4.19: Using a predefined component with its reference
  24. Listing 4.20: Using a predefined component in an array with its reference
  25. Listing 4.21: Deleting a product
  26. Listing 4.22: Describing a reusable parameter
  27. Listing 4.23: Using a predefined parameter
  28. Listing 4.24: Resource-level parameters
  29. Listing 5.1: A basic error response body
  30. Listing 5.2: A detailed error response
  31. Listing 5.3: A detailed error response using a generic type
  32. Listing 5.4: A detailed error response indicating an error source
  33. Listing 5.5: Returning multiple errors
  34. Listing 6.1: A bank account as a HAL document
  35. Listing 6.2: A money transfer as a Siren document
  36. Listing 6.3: Using the OPTIONS HTTP method
  37. Listing 6.4: A response indicating other available formats with the Link header
  38. Listing 8.1: Describing scopes
  39. Listing 8.2: Linking a goal to scopes
  40. Listing 8.3: Grouping scopes
  41. Listing 8.4: Linking a goal to scopes from different groups
  42. Listing 9.1: Activating a redirects flag on a Java HttpUrlConnection
  43. Listing 9.2: An informative error message
  44. Listing 10.1: A GraphQL API call and its response
  45. Listing 10.2: Retrieving some owner and account data
  46. Listing 10.3: Executing multiple queries
  47. Listing 10.4: Adding an updated balance to transactions
  48. Listing 11.1: The complete SSE specification
  49. Listing 11.2: The JSON schema of the update transaction goal’s body
  50. Listing 11.3: The JSON schema of the update transactions goal’s body
  51. Listing 11.4: A 207 Multi-Status response as described in RFC 4918
  52. Listing 11.5: The multi-status response’s JSON Schema
  53. Listing 11.6: An example generated using the JSON Schema
  54. Listing 11.7: An ISO 20022 IdentificationVerificationRequestV02 XML message
  55. Listing 11.8: An ISO 20022 IdentificationVerificationReportV02 XML message
  56. Listing 11.9: A GraphQL query
  57. Listing 11.10: A GraphQL response with an error
  58. Listing 12.1: A very complete description of a property with an example
  59. Listing 12.2: Documentation tools rely on descriptions to generate examples
  60. Listing 12.3: The transfer money goal’s basic reference documentation
  61. Listing 12.4: The transfer money goal overview’s OpenAPI Specification file
  62. Listing 12.5: Multiple examples of the transfer money goal’s request body
  63. Listing 12.6: A detailed error description
  64. Listing 12.7: Describing tags
  65. Listing 12.8: Defining API security and attaching scopes to a goal
  66. Listing 12.9: The info section of the underlying OpenAPI Specification file
  67. Listing 12.10: How ReDoc takes advantage of the OpenAPI Specification file
  68. Listing 12.11: Adding custom properties into an OpenAPI Specification file
  69. Listing 12.12: Security controls information on the get account goal
  70. Listing 12.13: Deprecating the List money transfers for admins goal
  71. Listing 12.14: Deprecating the t query parameter
  72. Listing 12.15: A response with a Sunset header
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset