-
Notifications
You must be signed in to change notification settings - Fork 41
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
9240cd9
commit aace2ee
Showing
13 changed files
with
330 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| This module outlines a structured approach for performing batch operations on APIs. The primary goal of batching is to enhance efficiency and scalability, particularly in scenarios where a client application needs to access multiple resources simultaneously. The module provides guidelines for request formatting, response handling, and error management. By adhering to these guidelines, developers can ensure seamless interoperability while improving system performance and reliability. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| # Collection resources | ||
|
|
||
| TODO | ||
|
|
||
| ## Collection request | ||
|
|
||
| <div class="rule" id="/batching/req-collection" data-type="technical"> | ||
| <p class="rulelab">Specify a list of collection requests when batching collection resources</p> | ||
| <dl> | ||
| <dt>Statement</dt> | ||
| <dd> | ||
| <p>When requesting a batch of collection resources, a list of collection requests must be specified.</p> | ||
| <div class="example"> | ||
| <p>Example request when requesting two address collection resources in a single batch operation:</p> | ||
| <pre> | ||
| // POST https://api.example.org/v1/adressen/_batch | ||
| { | ||
| "requests": [ | ||
| { "filter": { "postcode": "1234AB", "huisnummer": 1 }}, | ||
| { "filter": { "postcode": "3456XY", "huisnummer": 32 }} | ||
| ] | ||
| } | ||
| </pre> | ||
| </div> | ||
| </dd> | ||
| <dt>Rationale</dt> | ||
| <dd> | ||
| TODO | ||
| </dd> | ||
| <dt>Implications</dt> | ||
| <dd> | ||
| TODO | ||
| </dd> | ||
| </dl> | ||
| </div> | ||
|
|
||
| ## Collection response | ||
|
|
||
| TODO |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Batch endpoints | ||
|
|
||
| As described in the [[ADR]], there is a distinction between singular and collection resources. When applying batch operations, the request and response characteristics are different. | ||
|
|
||
| ## Request format | ||
|
|
||
| TODO | ||
|
|
||
| ## Response format | ||
|
|
||
| TODO |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # Existing standards | ||
|
|
||
| TODO |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| <!DOCTYPE html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta content="text/html; charset=utf-8" http-equiv="content-type" /> | ||
| <meta | ||
| name="viewport" | ||
| content="width=device-width, initial-scale=1, shrink-to-fit=no" | ||
| /> | ||
| <script | ||
| src="../../media/respec/organisation-config.js" | ||
| class="remove" | ||
| ></script> | ||
| <script src="js/config.js" class="remove"></script> | ||
| <script class="remove"> | ||
| const respecConfig = { ...organisationConfig, ...documentConfig }; | ||
| document.title = respecConfig.title; | ||
| </script> | ||
| <script | ||
| src="https://gitdocumentatie.logius.nl/publicatie/respec/builds/respec-nlgov.js" | ||
| class="remove" | ||
| async | ||
| ></script> | ||
| <script | ||
| class="remove" | ||
| src="https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js" | ||
| ></script> | ||
| <script src="../../media/respec/rules.js" class="remove"></script> | ||
| <link | ||
| rel="stylesheet" | ||
| type="text/css" | ||
| href="../../media/respec/style.css" | ||
| /> | ||
| <link | ||
| rel="shortcut icon" | ||
| type="image/x-icon" | ||
| href="https://tools.geostandaarden.nl/respec/style/logos/Geonovum.ico" | ||
| /> | ||
| </head> | ||
|
|
||
| <body> | ||
| <section | ||
| id="abstract" | ||
| data-include-format="markdown" | ||
| data-include="abstract.md" | ||
| ></section> | ||
| <section id="sotd"></section> | ||
| <section | ||
| id="introduction" | ||
| class="informative" | ||
| data-include-format="markdown" | ||
| data-include="introduction.md" | ||
| ></section> | ||
| <section | ||
| id="summary" | ||
| data-include-format="markdown" | ||
| data-include="summary.md" | ||
| ></section> | ||
| <section | ||
| id="endpoints" | ||
| class="informative" | ||
| data-include-format="markdown" | ||
| data-include="endpoints.md" | ||
| ></section> | ||
| <section | ||
| id="singular" | ||
| class="informative" | ||
| data-include-format="markdown" | ||
| data-include="singular.md" | ||
| ></section> | ||
| <section | ||
| id="collection" | ||
| class="informative" | ||
| data-include-format="markdown" | ||
| data-include="collection.md" | ||
| ></section> | ||
| <section | ||
| id="openapi-components" | ||
| class="informative" | ||
| data-include-format="markdown" | ||
| data-include="openapi-components.md" | ||
| ></section> | ||
| <section | ||
| id="existing-standards" | ||
| class="informative" | ||
| data-include-format="markdown" | ||
| data-include="existing-standards.md" | ||
| ></section> | ||
| </body> | ||
| </html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # Introduction | ||
|
|
||
| TODO |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| var documentConfig = { | ||
| title: "Batching", | ||
| specStatus: "wv", | ||
| specType: "st", | ||
| pubDomain: "api", | ||
| license: "cc-by", | ||
| shortName: "API-Strategie-mod-batching", | ||
| edDraftURI: | ||
| "https://github.com/Geonovum/KP-APIs/tree/master/API-strategie-modules/batching", | ||
| editors: [ | ||
| { | ||
| name: "Joost Farla", | ||
| company: "Geonovum", | ||
| companyURL: "https://www.geonovum.nl", | ||
| }, | ||
| ], | ||
| authors: [ | ||
| { | ||
| name: "Joost Farla", | ||
| company: "Geonovum", | ||
| companyURL: "https://www.geonovum.nl", | ||
| }, | ||
| { | ||
| name: "Frank Terpstra", | ||
| company: "Geonovum", | ||
| companyURL: "https://www.geonovum.nl", | ||
| }, | ||
| { | ||
| name: "Martin van der Plas", | ||
| company: "Logius", | ||
| companyURL: "https://www.logius.nl", | ||
| }, | ||
| { | ||
| name: "Peter Haasnoot", | ||
| company: "Logius", | ||
| companyURL: "https://www.logius.nl", | ||
| }, | ||
| { | ||
| name: "Pano Maria", | ||
| company: "Skemu", | ||
| companyURL: "https://skemu.com", | ||
| }, | ||
| ], | ||
| github: "https://github.com/Geonovum/KP-APIs", | ||
| }; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # OpenAPI components | ||
|
|
||
| TODO |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # Singular resources | ||
|
|
||
| TODO | ||
|
|
||
| ## Singular request | ||
|
|
||
| <div class="rule" id="/batching/req-singular" data-type="technical"> | ||
| <p class="rulelab">Specify a list of singular requests when batching singular resources</p> | ||
| <dl> | ||
| <dt>Statement</dt> | ||
| <dd> | ||
| <p>When requesting a batch of singular resources, a list of singular requests must be specified.</p> | ||
| <p>Each singular request must contain at least the unique identifier of the thing that the singular resource represents, using the <code>key</code> property. In most cases, things are identified by a single scalar value (string or number). However, they could also be identified by a compound value, consisting of multiple scalar values (in the resource URI, they would typically be represented by multiple path segments).</p> | ||
| <div class="example"> | ||
| <p>An example request for requesting two building resources in a single batch operation:</p> | ||
| <pre> | ||
| // POST https://api.example.org/v1/gebouwen/_batch | ||
| { | ||
| "requests": [ | ||
| { "key": "3b9710c4-6614-467a-ab82-36822cf48db1" }, | ||
| { "key": "609b0651-acad-4091-9144-432621df8bf8" } | ||
| ] | ||
| } | ||
| </pre> | ||
| </div> | ||
| <p>In case of a compound identifier, the value of the <code>key</code> property must be an array, in the exact same order as the path segments of the corresponding resource URI. The value type of the <code>key</code> property must be identical to the original value of the identifier. In case of a compound identifier, this could differ per part.</p> | ||
| <div class="example"> | ||
| <p>When a singular resource has a compound identifier, an array value must be provided. In this example, the first identifier part is a string, and the second part is numeric.</p> | ||
| <pre> | ||
| // POST https://api.example.org/v1/gebouwen/_batch | ||
| { | ||
| "requests": [ | ||
| { "key": ["key-1-part-1", 123] }, | ||
| { "key": ["key-2-part-1", 456] } | ||
| ] | ||
| } | ||
| </pre> | ||
| </div> | ||
| </dd> | ||
| <dt>Rationale</dt> | ||
| <dd> | ||
| TODO | ||
| </dd> | ||
| <dt>Implications</dt> | ||
| <dd> | ||
| TODO | ||
| </dd> | ||
| </dl> | ||
| </div> | ||
|
|
||
| ## Singular response | ||
|
|
||
| TODO |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| # Summary | ||
|
|
||
| ## List of technical rules | ||
|
|
||
| <ul id="technicalList"></ul> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.