@@ -598,7 +598,7 @@ ul.references li p a.back-anchor { This book is distributed under the Creative Commons Attribution-NonCommercial 4.0 International licence. Source code available at github.com/twirl/The-API-Book - Share: facebook · twitter · linkedin · redditTable of ContentsIntroductionChapter 1. On the Structure of This BookChapter 2. The API DefinitionChapter 3. Overview of Existing API Development SolutionsChapter 4. API Quality CriteriaChapter 5. The API-First ApproachChapter 6. On Backward CompatibilityChapter 7. On VersioningChapter 8. Terms and Notation KeysSection I. The API DesignChapter 9. The API Contexts PyramidChapter 10. Defining an Application FieldChapter 11. Separating Abstraction LevelsChapter 12. Isolating Responsibility AreasChapter 13. Describing Final InterfacesChapter 14. Annex to Section I. Generic API ExampleSection II. The API PatternsChapter 15. On Design Patterns in the API ContextChapter 16. Authenticating Partners and Authorizing API CallsChapter 17. Synchronization StrategiesChapter 18. Eventual ConsistencyChapter 19. Asynchronicity and Time ManagementChapter 20. Lists and Accessing ThemChapter 21. Bidirectional Data Flows. Push and Poll ModelsChapter 22. Multiplexing Notifications. Asynchronous Event ProcessingChapter 23. Atomicity of Bulk ChangesChapter 24. Partial UpdatesChapter 25. Degradation and PredictabilitySection III. The Backward CompatibilityChapter 26. The Backward Compatibility Problem StatementChapter 27. On the Waterline of the IcebergChapter 28. Extending through AbstractingChapter 29. Strong Coupling and Related ProblemsChapter 30. Weak CouplingChapter 31. Interfaces as a Universal PatternChapter 32. The Serenity Notepad[Work in Progress] Section IV. HTTP APIs & REST Architectural PrinciplesChapter 33. On the HTTP API Concept and TerminologyChapter 34. The REST MythChapter 35. Components of an HTTP Request and Their SemanticsChapter 36. Advantages and Disadvantages of HTTP APIsChapter 37. Organizing an HTTP API Based on the REST PrinciplesChapter 38. Working with HTTP API ErrorsChapter 39. Organizing the HTTP API Resources and OperationsChapter 40. Final Provisions and General Recommendations[Work in Progress] Section V. SDKs & UI LibrariesChapter 41. On the Content of This SectionChapter 42. The SDK: Problems and SolutionsChapter 43. The Code Generation PatternChapter 44. The UI ComponentsChapter 45. Decomposing UI ComponentsChapter 46. The MV* FrameworksChapter 47. The Backend-Driven UIChapter 48. Shared Resources and Asynchronous LocksChapter 49. Computed PropertiesChapter 50. ConclusionSection VI. The API ProductChapter 51. API as a ProductChapter 52. The API Business ModelsChapter 53. Developing a Product VisionChapter 54. Communicating with DevelopersChapter 55. Communicating with Business OwnersChapter 56. The API Services RangeChapter 57. The API Key Performance IndicatorsChapter 58. Identifying Users and Preventing FraudChapter 59. The Technical Means of Preventing ToS ViolationsChapter 60. Supporting customersChapter 61. The DocumentationChapter 62. The Testing EnvironmentChapter 63. Managing Expectations + Share: facebook · twitter · linkedin · redditTable of ContentsIntroductionChapter 1. On the Structure of This BookChapter 2. The API DefinitionChapter 3. Overview of Existing API Development SolutionsChapter 4. API Quality CriteriaChapter 5. The API-First ApproachChapter 6. On Backward CompatibilityChapter 7. On VersioningChapter 8. Terms and Notation KeysSection I. The API DesignChapter 9. The API Contexts PyramidChapter 10. Defining an Application FieldChapter 11. Separating Abstraction LevelsChapter 12. Isolating Responsibility AreasChapter 13. Describing Final InterfacesChapter 14. Annex to Section I. Generic API ExampleSection II. The API PatternsChapter 15. On Design Patterns in the API ContextChapter 16. Authenticating Partners and Authorizing API CallsChapter 17. Synchronization StrategiesChapter 18. Eventual ConsistencyChapter 19. Asynchronicity and Time ManagementChapter 20. Lists and Accessing ThemChapter 21. Bidirectional Data Flows. Push and Poll ModelsChapter 22. Multiplexing Notifications. Asynchronous Event ProcessingChapter 23. Atomicity of Bulk ChangesChapter 24. Partial UpdatesChapter 25. Degradation and PredictabilitySection III. The Backward CompatibilityChapter 26. The Backward Compatibility Problem StatementChapter 27. On the Waterline of the IcebergChapter 28. Extending through AbstractingChapter 29. Strong Coupling and Related ProblemsChapter 30. Weak CouplingChapter 31. Interfaces as a Universal PatternChapter 32. The Serenity Notepad[Work in Progress] Section IV. HTTP APIs & REST Architectural PrinciplesChapter 33. On the HTTP API Concept and TerminologyChapter 34. The REST MythChapter 35. Components of an HTTP Request and Their SemanticsChapter 36. Advantages and Disadvantages of HTTP APIsChapter 37. Organizing HTTP APIs Based on the REST PrinciplesChapter 38. Working with HTTP API ErrorsChapter 39. Organizing the HTTP API Resources and OperationsChapter 40. Final Provisions and General Recommendations[Work in Progress] Section V. SDKs & UI LibrariesChapter 41. On the Content of This SectionChapter 42. The SDK: Problems and SolutionsChapter 43. The Code Generation PatternChapter 44. The UI ComponentsChapter 45. Decomposing UI ComponentsChapter 46. The MV* FrameworksChapter 47. The Backend-Driven UIChapter 48. Shared Resources and Asynchronous LocksChapter 49. Computed PropertiesChapter 50. ConclusionSection VI. The API ProductChapter 51. API as a ProductChapter 52. The API Business ModelsChapter 53. Developing a Product VisionChapter 54. Communicating with DevelopersChapter 55. Communicating with Business OwnersChapter 56. The API Services RangeChapter 57. The API Key Performance IndicatorsChapter 58. Identifying Users and Preventing FraudChapter 59. The Technical Means of Preventing ToS ViolationsChapter 60. Supporting customersChapter 61. The DocumentationChapter 62. The Testing EnvironmentChapter 63. Managing Expectations § @@ -4829,7 +4829,7 @@ X-ApiName-Partner-Id: <partner_id> Estimate the overhead of preparing and introducing tools to decipher binary protocols versus the overhead of using not the most optimal data transfer protocols. Make an assessment of what is more important to you: having a quality but restricted in its capabilities set of bundled software or having the possibility of using a broad range of tools that work with HTTP APIs, even though their quality is not that high. Evaluate the cost of finding developers proficient with the format. -Chapter 37. Organizing an HTTP API Based on the REST Principles +Chapter 37. Organizing HTTP APIs Based on the REST Principles Now let's discuss the specifics: what does it mean exactly to “follow the protocol's semantics” and “develop applications in accordance with the REST architectural style”? Remember, we are talking about the following principles: Operations must be stateless @@ -4884,7 +4884,7 @@ HTTP/1.1 200 OK C and D call Service A to check the authentication token (passed as a proxied Authorization header or as an explicit request parameter) and return the requested data — the user's profile and the list of their orders. Service D merges the responses and sends them back to the client. -The original microservice mesh. Click to enlarge +The original microservice mesh. Click to enlarge It is quite obvious that in this setup, we put excessive load on the authorization service as every nested microservice now needs to query it. Even if we abolish checking the authenticity of internal requests, it won't help as services B and C can't know the identifier of the user. Naturally, this leads to the idea of propagating the once-retrieved user_id through the microservice mesh: Gateway D receives a request and exchanges the token for user_id through service A @@ -4896,7 +4896,7 @@ and service C: -Step 2. Adding explicit user identifiers. Click to enlarge +Step 2. Adding explicit user identifiers. Click to enlarge NB: we used the /v1/orders?user_id notation and not, let's say, /v1/users/{user_id}/orders, because of two reasons: @@ -4950,7 +4950,7 @@ If-None-Match: <revision> -Step 2. Adding server-side caches. Click to enlarge +Step 2. Adding server-side caches. Click to enlarge By employing this approach [using ETags to control caching], we automatically get another pleasant bonus. We can reuse the same data in the order creation endpoint design. In the optimistic concurrency control paradigm, the client must pass the actual revision of the orders resource to change its state: POST /v1/orders HTTP/1.1 If-Match: <revision> @@ -4967,7 +4967,7 @@ ETag: <new revision> { /* The updated list of orders */ } and gateway D will update the cache with the current data snapshot. -Creating a new order. Click to enlarge +Creating a new order. Click to enlarge Importantly, after this API refactoring, we end up with a system in which we can remove gateway D and make the client itself perform its duty. Nothing prevents the client from: Storing user_id on its side (or retrieving it from the token, if the format allows it) as well as the last known ETag of the order list diff --git a/docs/API.en.pdf b/docs/API.en.pdf index 47c49a1..f446ded 100644 Binary files a/docs/API.en.pdf and b/docs/API.en.pdf differ diff --git a/docs/API.ru.epub b/docs/API.ru.epub index 5282abe..c709a47 100644 Binary files a/docs/API.ru.epub and b/docs/API.ru.epub differ diff --git a/docs/API.ru.pdf b/docs/API.ru.pdf index 27b8dc4..6cb64a9 100644 Binary files a/docs/API.ru.pdf and b/docs/API.ru.pdf differ diff --git a/docs/index.html b/docs/index.html index c1f7686..0133e36 100644 --- a/docs/index.html +++ b/docs/index.html @@ -113,7 +113,7 @@ Chapter 34. The REST Myth Chapter 35. Components of an HTTP Request and Their Semantics Chapter 36. Advantages and Disadvantages of HTTP APIs -Chapter 37. Organizing an HTTP API Based on the REST Principles +Chapter 37. Organizing HTTP APIs Based on the REST Principles Chapter 38. Working with HTTP API Errors Chapter 39. Organizing the HTTP API Resources and Operations Chapter 40. Final Provisions and General Recommendations diff --git a/src/en/clean-copy/05-[Work in Progress] Section IV. HTTP APIs & REST Architectural Principles/05.md b/src/en/clean-copy/05-[Work in Progress] Section IV. HTTP APIs & REST Architectural Principles/05.md index d972ec1..ce16a50 100644 --- a/src/en/clean-copy/05-[Work in Progress] Section IV. HTTP APIs & REST Architectural Principles/05.md +++ b/src/en/clean-copy/05-[Work in Progress] Section IV. HTTP APIs & REST Architectural Principles/05.md @@ -1,4 +1,4 @@ -### [Organizing an HTTP API Based on the REST Principles][http-api-rest-organizing] +### [Organizing HTTP APIs Based on the REST Principles][http-api-rest-organizing] Now let's discuss the specifics: what does it mean exactly to “follow the protocol's semantics” and “develop applications in accordance with the REST architectural style”? Remember, we are talking about the following principles: * Operations must be stateless diff --git a/src/en/graphs/http-api-organizing-01.mermaid b/src/en/graphs/http-api-organizing-01.mermaid index a99a6d9..2904432 100644 --- a/src/en/graphs/http-api-organizing-01.mermaid +++ b/src/en/graphs/http-api-organizing-01.mermaid @@ -3,7 +3,7 @@ sequenceDiagram participant D as Gateway D participant A as AuthorizationService A participant B as User ProfilesService B - participant C as OrderService C + participant C as OrdersService C U->>+D: GET /v1/stateAuthorization: Bearer #60;token#62; par D->>+B: GET /v1/profile diff --git a/src/en/graphs/http-api-organizing-02.mermaid b/src/en/graphs/http-api-organizing-02.mermaid index 460cc5d..9380f2c 100644 --- a/src/en/graphs/http-api-organizing-02.mermaid +++ b/src/en/graphs/http-api-organizing-02.mermaid @@ -3,7 +3,7 @@ sequenceDiagram participant D as Gateway D participant A as AuthorizationService A participant B as User ProfilesService B - participant C as OrderService C + participant C as OrdersService C U->>+D: GET /v1/stateAuthorization: Bearer #60;token#62; D->>+A: GET /v1/auth#60;token#62; A-->>-D: { status, user_id } diff --git a/src/en/graphs/http-api-organizing-03.mermaid b/src/en/graphs/http-api-organizing-03.mermaid index dfe0149..7c1cff3 100644 --- a/src/en/graphs/http-api-organizing-03.mermaid +++ b/src/en/graphs/http-api-organizing-03.mermaid @@ -3,7 +3,7 @@ sequenceDiagram participant D as Gateway D participant A as AuthorizationService A participant B as User ProfilesService B - participant C as OrderService C + participant C as OrdersService C U->>+D: GET /v1/stateAuthorization: Bearer #60;token#62; D->>+A: GET /v1/auth A-->>-D: { status, user_id } diff --git a/src/en/graphs/http-api-organizing-04.mermaid b/src/en/graphs/http-api-organizing-04.mermaid index 58125eb..ba84a45 100644 --- a/src/en/graphs/http-api-organizing-04.mermaid +++ b/src/en/graphs/http-api-organizing-04.mermaid @@ -3,7 +3,7 @@ sequenceDiagram participant D as Gateway D participant A as AuthorizationService A participant B as User ProfilesService B - participant C as OrderService C + participant C as OrdersService C U->>+D: POST /v1/orders HTTP/1.1If-Match: #60;revision#62;Authorization: Bearer #60;token#62; D->>+A: GET /v1/auth A-->>-D: { status, user_id } diff --git a/src/img/graphs/http-api-organizing-01.en.png b/src/img/graphs/http-api-organizing-01.en.png index 316151f..5ab93f5 100644 Binary files a/src/img/graphs/http-api-organizing-01.en.png and b/src/img/graphs/http-api-organizing-01.en.png differ diff --git a/src/img/graphs/http-api-organizing-02.en.png b/src/img/graphs/http-api-organizing-02.en.png index 1d2755b..a4d366f 100644 Binary files a/src/img/graphs/http-api-organizing-02.en.png and b/src/img/graphs/http-api-organizing-02.en.png differ diff --git a/src/img/graphs/http-api-organizing-03.en.png b/src/img/graphs/http-api-organizing-03.en.png index efef19e..7b3397e 100644 Binary files a/src/img/graphs/http-api-organizing-03.en.png and b/src/img/graphs/http-api-organizing-03.en.png differ diff --git a/src/img/graphs/http-api-organizing-04.en.png b/src/img/graphs/http-api-organizing-04.en.png index b379b73..853b1c4 100644 Binary files a/src/img/graphs/http-api-organizing-04.en.png and b/src/img/graphs/http-api-organizing-04.en.png differ diff --git a/src/templates.js b/src/templates.js index a883f2c..5103079 100644 --- a/src/templates.js +++ b/src/templates.js @@ -235,7 +235,7 @@ module.exports = { aImg: ({ src, href, title, alt, l10n, className = 'img-wrapper' }) => { const fullTitle = escapeHtml( `${title}${title.at(-1).match(/[\.\?\!\)]/) ? ' ' : '. '} ${ - alt == 'PD' ? l10n.publicDomain : `${l10n.imageCredit}: ${alt}` + alt == 'CTL' ? l10n.ctl : `${l10n.imageCredit}: ${alt}` }` ); return `
