Asynchronous web endpoints

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.

Use the bin/magento queue:consumers:start async.operations.all command to start the consumer that handles asynchronous and bulk API messages.

Magento supports the following types of asynchronous requests:

• POST
• PUT
• DELETE
• PATCH

GET requests are not supported. Although Magento does not currently implement any PATCH requests, they are supported in custom extensions.

The route to all asynchronous calls contains the prefix /async, added before /V1 of a standard synchronous endpoint. For example:

1
2
POST /async/V1/products
PUT /async/V1/products/:sku

Magento Open Source and Magento Commerce installations support asynchronous web endpoints.

The REST API documentation provides a list of all current synchronous Magento API routes.

The response of an asynchronous request contains the following fields:

Sample usage

The following call asynchronously changes the price of the product that has a sku of 24-MB01:

1
PUT <host>/rest/<store_code>/async/V1/products/24-MB01

Payload

1
2
3
4
5
{
  "product": {
    "price": 29
  }
}

Response

Magento generates a bulk_uuid for each asynchronous request. Use the bulk_uuid to determine the operation status of your request.

1
2
3
4
5
6
7
8
9
10
11
{
    "bulk_uuid": "fbfca270-7a90-4c4e-9f32-d6cf3728cdc7",
    "request_items": [
        {
            "id": 0,
            "data_hash": null,
            "status": "accepted"
        }
    ],
    "errors": false
}

Store scopes

You can specify a store code in the route of an asynchronous endpoint so that it operates on a specific store, as shown below:

1
2
POST /<store_code>/async/V1/products
PUT /<store_code>/async/V1/products/:sku

As a result, the asynchronous calls update the products on the specific store, instead of the default store.

You can specify the all store code to perform operations on all existing stores:

1
2
POST /all/async/V1/products
PUT /all/async/V1/products/:sku

Fallback and creating/updating objects when setting store scopes

The following rules apply when you create or update an object, such as a product.

• If you do not set the store code while creating a new product, Magento creates a new object with all values set globally for each scope.
• If you do not set the store code while updating a product, then by fallback, Magento updates values for the default store only.
• If you include the all parameter, then Magento updates values for all store scopes (in case a particular store doesn’t yet have its own value set).
• If <store_code> parameter is set, then values for only defined store will be updated.