Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update batch-operations.md

Browse Source
This commit is contained in:
Z
2017-06-26 09:03:02 +02:00
committed by GitHub
parent fabd509c31
commit 3d4cf54739
1 changed files with 7 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
execution/batch-operations.md
View File

@@ -1,7 +1,7 @@
# Batch Operations # Batch Operations
## Processing Similar Resources ## Processing Similar Resources
An operation that needs to process several similar resource in bulk **SHOULD** use a collection resource with the appropriate HTTP Request Method. When processing existing resource the request message body **MUST** contain the URLs of the respective resources being processed. An operation that needs to process several related resources in bulk **SHOULD** use a collection resource with the appropriate HTTP Request Method. When processing existing resource the request message body **MUST** contain the URLs of the respective resources being processed.
#### Example #### Example
##### Create Multiple Orders at Once ##### Create Multiple Orders at Once
@@ -24,7 +24,7 @@ Content-Type: application/json
##### Update Multiple Orders at Once ##### Update Multiple Orders at Once
> NOTE: The self link relation clearly identifies the existing resource being edited. > NOTE: The self-link relation identifies the existing resource being edited.
``` ```
PATCH /orders PATCH /orders
@@ -51,11 +51,11 @@ Content-Type: application/json
## Results of Bulk Operation ## Results of Bulk Operation
Every bulk operation **MUST** be atomic and treated as any other operation. Every bulk operation **MUST** be atomic and treated as any other operation.
> _The server must implement bulk requests as atomic. If the request is for creating 10 addresses, the server should create all 10 addresses before returning a successful response code. The server should not commit changes partially in the case of failures._ > _The server must implement bulk requests as atomic. If the request is for creating ten addresses, the server should create all ten addresses before returning a successful response code. The server should not commit changes partially in the case of failures._
## DO NOT USE "POST Tunneling" ## DO NOT USE "POST Tunneling."
Every API **MUST** avoid tunneling multiple HTTP Request using one POST request. Instead provide an application-specific resource to process the batch request. Every API **MUST** avoid tunneling multiple HTTP Request using one POST request. Instead, provide an application-specific resource to process the batch request.
## Non-atomic Bulk Operations ## Non-atomic Bulk Operations
@@ -63,9 +63,9 @@ Non-atomic bulk operations are **strongly discouraged** as they bring additional
The suggestion is to **split** a non-atomic operation into several atomic operations. The cost of few more calls will be greatly outweighed but the cleaner design, clarity and easier maintainability. The suggestion is to **split** a non-atomic operation into several atomic operations. The cost of few more calls will be greatly outweighed but the cleaner design, clarity and easier maintainability.
However, in such an operation has to be provided such an non-atomic bulk operation **MUST** conform to the following guidelines. However, in such an operation has to be provided such a non-atomic bulk operation **MUST** conform to the following guidelines.
1. Non-atomic bulk operation **MUST** return a success status code (e.g. **200 OK**) only if every and all sub-operation succeded. 1. Non-atomic bulk operation **MUST** return a success status code (e.g. **200 OK**) only if every and all sub-operation succeeded.
1. If any single one sub-operation fails the whole non-atomic bulk operation **MUST** return the respective **4xx** or **5xx** status code. 1. If any single one sub-operation fails the whole non-atomic bulk operation **MUST** return the respective **4xx** or **5xx** status code.
@@ -134,8 +134,3 @@ Content-Type: application/problem+json
``` ```
The `processed` field should contain the result of processed sub-operations as if they were returned in a 200 OK. The `processed` field should contain the result of processed sub-operations as if they were returned in a 200 OK.