diff --git a/execution/batch-operations.md b/execution/batch-operations.md index f31689e..0a39cdd 100644 --- a/execution/batch-operations.md +++ b/execution/batch-operations.md @@ -1,7 +1,7 @@ # Batch Operations ## 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 ##### Create Multiple Orders at Once @@ -24,7 +24,7 @@ Content-Type: application/json ##### 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 @@ -51,11 +51,11 @@ Content-Type: application/json ## Results of Bulk 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" -Every API **MUST** avoid tunneling multiple HTTP Request using one POST request. Instead provide an application-specific resource to process the batch request. +## 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. ## 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. -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. @@ -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. - - - - -