Skip to content

Commit 3210507

Browse files
nuzilkeharper
nuzil
authored and
keharper
committed
Add Documentation for Asynchronous WebApi Endpoints (magento#2363)
* Add Documentation for Asynchronous WebApi Endpoins * Update asynchronous-web-endpoints.md First round of revisions * Add Documentation for Operation Status Endpoints * Update operation-status-endpoints.md * Add Response format and reference to Operation Statuses * Fix link * Update asynchronous-web-endpoints.md * Update operation-status-endpoints.md * Update asynchronous-web-endpoints.md * Update asynchronous-web-endpoints.md * Update operation-status-endpoints.md * Update asynchronous-web-endpoints.md * Update operation-status-endpoints.md * Update asynchronous-web-endpoints.md * Update operation-status-endpoints.md * Add description for serialized_data and result_serialized_data * Update operation-status-endpoints.md * Update asynchronous-web-endpoints.md * Update operation-status-endpoints.md * Update operation-status-endpoints.md
1 parent 5180184 commit 3210507

File tree

2 files changed

+199
-5
lines changed

2 files changed

+199
-5
lines changed

‎guides/v2.3/rest/asynchronous-web-endpoints.md‎

Lines changed: 72 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,78 @@
22
group: rest
33
title: Asynchronous web endpoints
44
version: 2.3
5-
contributor_name: Oleksandr Lykun
6-
contributor_link:
5+
contributor_name: comwrap GmbH
6+
contributor_link: http://comwrap.com/
77
functional_areas:
88
- Integration
99
---
10+
11+
An asynchronous web endpoint intercepts messages to a Web API and writes them to the message queue. Each time the system accepts such an API request, it generates a UUID identifier. Magento includes this UUID when it adds the message to the queue. Then, a consumer reads the messages from the queue and executes them one-by-one.
12+
13+
Magento supports the following types of asynchronous requests:
14+
15+
* POST
16+
* PUT
17+
* DELETE
18+
* PATCH
19+
20+
{:.bs-callout .bs-callout-info}
21+
GET requests are not supported. Although Magento does not currently implement any PATCH requests, they are supported in custom extensions.
22+
23+
The route to all asynchronous calls contains the prefix `/async`, added before `/V1` of a standard synchronous endpoint. For example:
24+
25+
```
26+
POST /async/V1/products
27+
PUT /async/V1/products/:sku
28+
DELETE /async/V1/products/:sku
29+
```
30+
31+
{{site.data.var.ce}} and {{site.data.var.ee}} installations support asynchronous web endpoints.
32+
33+
The [Swagger documentation]({{ site.baseurl }}/swagger/index.html) provides a list of all current synchronous Magento API routes.
34+
35+
The response of an asynchronous request contains the following fields:
36+
37+
Field name | Data type | Description
38+
--- | --- | ---
39+
`bulk_uuid` | String | A generated universally unique identifier.
40+
`request_items` | Object | An array containing information about the status of the asynchronous request.
41+
`id` | Integer | A generated ID that identifies the request.
42+
`data_hash` | String | Reserved for future use. Currently, the value is always `null`.
43+
`status` | String | Reserved for future use. Currently, the value is always `accepted`.
44+
`errors` | Boolean | Reserved for future use. Currently, the value is always `false`. If an error occurs, the system provides all error-related information as a standard `webapi` exception.
45+
46+
## Sample usage
47+
48+
The following call asynchronously changes the price of the product that has a `sku` of `24-MB01`:
49+
50+
PUT /async/V1/products/24-MB01
51+
52+
## Payload
53+
54+
``` json
55+
{
56+
"product": {
57+
"price": 29
58+
}
59+
}
60+
```
61+
62+
## Response
63+
64+
Magento generates a `bulk_uuid` for each asynchronous request. Use the `bulk_uuid` to determine the [operation status]({{ page.baseurl }}/rest/operation-status-endpoints.html) of your request.
65+
66+
``` json
67+
{
68+
"bulk_uuid": "fbfca270-7a90-4c4e-9f32-d6cf3728cdc7",
69+
"request_items": [
70+
{
71+
"id": 0,
72+
"data_hash": null,
73+
"status": "accepted"
74+
}
75+
],
76+
"errors": false
77+
}
78+
```
79+

‎guides/v2.3/rest/operation-status-endpoints.md‎

Lines changed: 127 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,133 @@
11
---
22
group: rest
3-
title: Status endpoints
3+
title: Bulk operation status endpoints
44
version: 2.3
5-
contributor_name: Oleksandr Lykun
6-
contributor_link:
5+
contributor_name: comwrap GmbH
6+
contributor_link: https://www.comwrap.com/
77
functional_areas:
88
- Integration
99
---
10+
11+
Magento generates a `bulk_uuid` each time it executes an [asynchronous API request]({{ page.baseurl }}/rest/asynchronous-web-endpoints.html). You can track the status of an asynchronous operation with the following endpoints:
12+
13+
* `GET /V1/bulk/:bulkUuid/status`
14+
* `GET /V1/bulk/:bulkUuid/detailed-status`
15+
16+
17+
## Get the status summary
18+
19+
The `GET /V1/bulk/:bulkUuid/status` endpoint returns the abbreviated status of the specified operation:
20+
21+
Field name | Data type | Description
22+
--- | --- | ---
23+
`operations_list` | Object | An array containing information about each operation in a bulk or asynchronous request.
24+
`id` | Integer | Identifies the bulk or asynchronous request.
25+
`status` | Integer | The operation status <br/>* `1` = Complete <br/>* `2` = The operation failed, but you can try to perform it again<br/>* `3` = The operation failed. You must change something to retry it.<br/>* `4` = Open<br/>* `5` = Rejected
26+
`result_message` | String | Describes the result of the operation. If successful, the value contains the string `Service execution success` as well as the method that executed the operation.
27+
`error_code` | Integer | If applicable, an error code associated with the operation.
28+
`extension_attributes` | Object | Lists extension attributes.
29+
`bulk_id` " String | UUID generated by an [asynchronous API request]({{ page.baseurl }}/rest/asynchronous-web-endpoints.html) or [Bulk API request]({{ page.baseurl }}/rest/bulk-endpoints.md).
30+
`description` | String | Contains the message queue topic.
31+
`start_time` | String | The time that a bulk or asynchronous operation started.
32+
`user_id` | Integer | The user ID that executed the request.
33+
`operation_count` | Integer | The number of operations processed in the request.
34+
35+
**Response**
36+
37+
```json
38+
{
39+
"operations_list": [
40+
{
41+
"id": 12,
42+
"status": 1,
43+
"result_message": "Service execution success Magento\\Catalog\\Model\\ProductRepository\\Interceptor::save",
44+
"error_code": null
45+
}
46+
],
47+
"bulk_id": "fbfca270-7a90-4c4e-9f32-d6cf3728cdc7",
48+
"description": "Topic async.V1.products.sku.PUT",
49+
"start_time": "2018-07-12 16:07:53",
50+
"user_id": null,
51+
"operation_count": 1
52+
}
53+
```
54+
55+
## Get the detailed status
56+
57+
The `GET /V1/bulk/:bulkUuid/detailed-status` endpoint returns detailed information about status of a specified operation. It is similar to the `GET /V1/bulk/:bulkUuid/status` endpoint, except that the `operations_list` array also contains the message queue topic name and serialized data for each operation.
58+
59+
```
60+
GET /V1/bulk/:bulkUuid/detailed-status
61+
```
62+
63+
Field name | Data type | Description
64+
--- | --- | ---
65+
`operations_list` | Object | An array containing information about each operation in a bulk or asynchronous request.
66+
`id` | Integer | Identifies the bulk or asynchronous request.
67+
`bulk_uuid` | String | UUID generated by an [asynchronous API request]({{ page.baseurl }}/rest/asynchronous-web-endpoints.html) or [Bulk API request]({{ page.baseurl }}/rest/bulk-endpoints.md).
68+
`topic_name` | String | The message queue topic.
69+
`serialized_data` | String | An array of serialized input data. It contains serialized JSON with the following keys: `entity_id` - `null`, `entity_link` - an empty string, `meta_info` - the body of the API request that was executed.
70+
`result_serialized_data` | String | Contains serialized output of the corresponding synchronous API call. For example, if you call `POST /async/V1/products`, this field contains serialized response from `POST /V1/products`.
71+
`status` | Integer | The operation status <br/>* `1` = Complete <br/>* `2` = The operation failed, but you can try to perform it again<br/>* `3` = The operation failed. You must change something to retry it.<br/>* `4` = Open<br/>* `5` = Rejected
72+
`result_message` | String | Describes the result of the operation. If successful, the value contains the string `Service execution success` as well as the method that executed the operation.
73+
`error_code` | Integer | If applicable, an error code associated with the operation.
74+
`extension_attributes | Object | Lists extension attributes.
75+
`bulk_id` " String | UUID generated by an [asynchronous API request]({{ page.baseurl }}/rest/asynchronous-web-endpoints.html) or [Bulk API request]({{ page.baseurl }}/rest/bulk-endpoints.md).
76+
`description` | String | Contains the message queue topic.
77+
`start_time` | String | The time that a bulk or asynchronous operation started.
78+
`user_id` | Integer | The user ID that executed the request.
79+
`operation_count` | Integer | The number of operations processed in the request.
80+
81+
**Response**
82+
83+
```json
84+
{
85+
"operations_list": [
86+
{
87+
"id": 4,
88+
"bulk_uuid": "c43ed402-3dd3-4100-92e2-dc5852d3009b",
89+
"topic_name": "async.V1.customers.POST",
90+
"serialized_data": "{\"entity_id\":null,\"entity_link\":\"\",\"meta_information\":\"{\\\"customer\\\":{\\\"email\\\":\\\"[email protected]\\\",\\\"firstname\\\":\\\"Melanie Shaw\\\",\\\"lastname\\\":\\\"Doe\\\"},\\\"password\\\":\\\"Password1\\\",\\\"redirectUrl\\\":\\\"\\\"}\"}",
91+
"result_serialized_data": null,
92+
"status": 3,
93+
"result_message": "A customer with the same email address already exists in an associated website.",
94+
"error_code": 0
95+
},
96+
{
97+
"id": 5,
98+
"bulk_uuid": "c43ed402-3dd3-4100-92e2-dc5852d3009b",
99+
"topic_name": "async.V1.customers.POST",
100+
"serialized_data": "{\"entity_id\":null,\"entity_link\":\"\",\"meta_information\":\"{\\\"customer\\\":{\\\"email\\\":\\\"[email protected]\\\",\\\"firstname\\\":\\\"Bryce\\\",\\\"lastname\\\":\\\"Martin\\\"},\\\"password\\\":\\\"Password1\\\",\\\"redirectUrl\\\":\\\"\\\"}\"}",
101+
"result_serialized_data": null,
102+
"status": 3,
103+
"result_message": "A customer with the same email address already exists in an associated website.",
104+
"error_code": 0
105+
},
106+
{
107+
"id": 6,
108+
"bulk_uuid": "c43ed402-3dd3-4100-92e2-dc5852d3009b",
109+
"topic_name": "async.V1.customers.POST",
110+
"serialized_data": "{\"entity_id\":null,\"entity_link\":\"\",\"meta_information\":\"{\\\"customer\\\":{\\\"email\\\":\\\"[email protected]\\\",\\\"firstname\\\":\\\"Bryce\\\",\\\"lastname\\\":\\\"Martin\\\"},\\\"password\\\":\\\"Password1\\\",\\\"redirectUrl\\\":\\\"\\\"}\"}",
111+
"result_serialized_data": null,
112+
"status": 3,
113+
"result_message": "A customer with the same email address already exists in an associated website.",
114+
"error_code": 0
115+
},
116+
{
117+
"id": 7,
118+
"bulk_uuid": "c43ed402-3dd3-4100-92e2-dc5852d3009b",
119+
"topic_name": "async.V1.customers.POST",
120+
"serialized_data": "{\"entity_id\":null,\"entity_link\":\"\",\"meta_information\":\"{\\\"customer\\\":{\\\"email\\\":\\\"[email protected]\\\",\\\"firstname\\\":\\\"Teresa\\\",\\\"lastname\\\":\\\"Gomez\\\"},\\\"password\\\":\\\"Password1\\\",\\\"redirectUrl\\\":\\\"\\\"}\"}",
121+
"result_serialized_data": null,
122+
"status": 3,
123+
"result_message": "A customer with the same email address already exists in an associated website.",
124+
"error_code": 0
125+
}
126+
],
127+
"bulk_id": "c43ed402-3dd3-4100-92e2-dc5852d3009b",
128+
"description": "Topic async.V1.customers.POST",
129+
"start_time": "2018-07-11 20:07:14",
130+
"user_id": null,
131+
"operation_count": 4
132+
}
133+
```

0 commit comments

Comments
 (0)