Construct a request

To configure a web API, developers define some of the elements of each API call in the <module root dir>/vendor/<vendor-name>/<module-name>/etc/webapi.xml file, where <vendor-name> is your vendor name (for example, magento) and <module-name> is your module name (which exactly matches its definition in composer.json). For example, the web API for the Customer service is defined in the <magento_root>/vendor/magento/module-customer/etc/webapi.xml configuration file. Service data interfaces and builders define the required and optional parameters and the return values for the API calls.

Overview

The following table and the sections that follow the table describe web API call elements:

HTTP verb

Specify one of these HTTP verbs in the request:

• GET. Requests transfer of a current representation of the target resource. If you omit the verb, GET is the default.
• PUT. Requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.
• POST. Requests that the origin server accept the representation enclosed in the request as data to be processed by the target resource.
• DELETE. Requests that the origin server delete the target resource.

Endpoint

An endpoint is a combination of the server that fulfills a request, the web service, the store code, the resource against which the request is being made, and any template parameters.

For example, in the http://magento.ll/index.php/rest/default/V1/customerGroups/:id endpoint, the server is magento.ll/index.php/, the web service is rest, the resource is /V1/customerGroups, and the template parameter is id.

A store code can have one of the following values.

• The store’s assigned store code.
• default. This is the default value when no store code is provided.
• all. This value only applies to endpoints defined in the CMS and Product modules. If this value is specified, the API call affects all of the merchant’s stores.

HTTP headers

To specify an HTTP header in a cURL command, use the -H option.

Specify one or more of the following HTTP headers in your web API calls:

Call payload

The call payload is a set of input parameters and attributes that you supply with the request. API operations have both required and optional inputs.

You specify input parameters in the URI. For example, in the GET/V1/customers/:customerId URI, you must specify the customerId template parameter. This parameter filters the response by the specified customer ID.

You specify input attributes in a JSON- or XML-formatted request body. For example, in the POST /V1/customers call, you must specify a request body like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "customer": {
        "email": "user@example.com",
        "firstname": "John",
        "lastname": "Doe"
    },
    "addresses": [
        {
            "defaultShipping": true,
            "defaultBilling": true,
            "firstname": "John",
            "lastname": "Doe",
            "region": {
                "regionCode": "CA",
                "region": "California",
                "regionId": 12
            },
            "postcode": "90001",
            "street": ["Zoe Ave"],
            "city": "Los Angeles",
            "telephone": "555-000-00-00",
            "countryId": "US"
        }
    ]
}

This JSON-formatted request body includes a customer object with the customer email, first name, and last name, and customer address information. The information in this request body is used to populate the new customer account.

Construct a request

This example shows you how to construct a REST web API call to create an account.

1. Open the Magento/Customer/etc/webapi.xml

2. Find the route element that defines the createAccount call:

   1
   2
   3
   4
   5
   6
   <route url="/V1/customers" method="POST">
      <service class="Magento\Customer\Api\AccountManagementInterface" method="createAccount"/>
      <resources>
         <resource ref="anonymous"/>
      </resources>
   </route>
   

3. Use the method and url values on the route element to construct the URI. In this example, the URI is POST /V1/customers.

4. Use the class attribute on the service element to identify the service interface. In this example, the service interface is the AccountManagementInterface PHP file.

   Open the AccountManagementInterface.php file and find the createAccount method, as follows:

   1
   2
   3
   4
   5
   public function createAccount(
        \Magento\Customer\Api\Data\CustomerInterface $customer,
        $password = null,
        $redirectUrl = ''
    )
   

   The createAccount call requires a customer data object. The password and redirectUrl values are optional. The default password value is null and the default redirectUrl value is blank.

5. To pass the customer data object in the POST call payload, specify JSON or XML request body on the call.

Customers Search API request example

The following example builds a Customers Search request based on search criteria. It returns a list of customers that match given search criteria.

1. Prepare Authorization, Accept and Content-Type headers to be passed to a request object. Use the Authorization token returned by the Magento token service.

   1
   2
   3
   4
   5
   6
   7
   $token = 'token';
   $httpHeaders = new \Zend\Http\Headers();
   $httpHeaders->addHeaders([
      'Authorization' => 'Bearer ' . $token,
      'Accept' => 'application/json',
      'Content-Type' => 'application/json'
   ]);
   

2. Open the Magento/Customer/etc/webapi.xml configuration file and find the CustomerRepositoryInterface interface with the getList method.

3. Set the headers, URI and method to a request object. Use URI /V1/customers/search and method GET values. Use the searchCriteria parameter to complete the Customer Search query. See searchCriteria usage.

   The following example finds customers whose first name contains “ver” or whose last name contains “Costello”.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
    $request = new \Zend\Http\Request();
    $request->setHeaders($httpHeaders);
    $request->setUri('http://magento.ll/rest/V1/customers/search');
    $request->setMethod(\Zend\Http\Request::METHOD_GET);
   
    $params = new \Zend\Stdlib\Parameters([
        'searchCriteria' => [
            'filterGroups' => [
                0 => [
                    'filters' => [
                        0 => [
                            'field' => 'firstname',
                            'value' => '%ver%',
                            'condition_type' => 'like'
                        ],
                        1 => [
                            'field' => 'lastname',
                            'value' => '%Costello%',
                            'condition_type' => 'like'
                        ]
                    ]
                ]
            ],
            'current_page' => 1,
            'page_size' => 10
        ],
    ]);
   
    $request->setQuery($params);
   

4. Prepare a HTTP Curl client object and pass the request object to Client::send() method.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   $client = new \Zend\Http\Client();
   $options = [
      'adapter'   => 'Zend\Http\Client\Adapter\Curl',
      'curloptions' => [CURLOPT_FOLLOWLOCATION => true],
      'maxredirects' => 0,
      'timeout' => 30
    ];
    $client->setOptions($options);
   
    $response = $client->send($request);
   

This request returns a list of all customers in JSON format, as shown below. You can also specify XML format by changing Accept header of the request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
    "items": [
        {
            "id": 1,
            "group_id": 1,
            "default_billing": "1",
            "default_shipping": "1",
            "created_at": "2017-12-05 09:50:11",
            "updated_at": "2018-09-22 06:32:50",
            "created_in": "Default Store View",
            "dob": "1973-12-15",
            "email": "roni_cost@example.com",
            "firstname": "Veronica",
            "lastname": "Costello",
            "gender": 2,
            "store_id": 1,
            "website_id": 1,
            "addresses": [
                {
                    "id": 1,
                    "customer_id": 1,
                    "region": {
                        "region_code": "MI",
                        "region": "Michigan",
                        "region_id": 33
                    },
                    "region_id": 33,
                    "country_id": "US",
                    "street": [
                        "6146 Honey Bluff Parkway"
                    ],
                    "telephone": "(555) 229-3326",
                    "postcode": "49628-7978",
                    "city": "Calder",
                    "firstname": "Veronica",
                    "lastname": "Costello",
                    "default_shipping": true,
                    "default_billing": true
                },
                {
                    "id": 19,
                    "customer_id": 1,
                    "region": {
                        "region_code": "London ",
                        "region": "London ",
                        "region_id": 0
                    },
                    "region_id": 0,
                    "country_id": "GB",
                    "street": [
                        "1 Studio 103 The Business Centre 61"
                    ],
                    "telephone": "1234567890",
                    "postcode": "CF24 3DG",
                    "city": "Tottenham ",
                    "firstname": "Veronica",
                    "lastname": "Costello"
                }
            ],
            "disable_auto_group_change": 0
        }
    ],
    "search_criteria": {
        "filter_groups": [
            {
                "filters": [
                    {
                        "field": "firstname",
                        "value": "%ver%",
                        "condition_type": "like"
                    }
                ]
            }
        ]
    },
    "total_count": 1
}

Related topics

Run the web API call through a cURL command or a REST client.