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 <your Magento install dir>/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

Each Magento web API call contains of a combination of these elements:

• HTTP verb
• Endpoint
• HTTP headers
• Call payload

The following table and the sections that follow the table describe these 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 resource against which the request is being made, and any template parameters.

For example, in the http://magento.ll/index.php/rest/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.

HTTP headers

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

Authorization

Authorization: Bearer <TOKEN>

Accept

Accept: application/<FORMAT>

Content-Type:application/<FORMAT>

Call payload

The call payload is 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:

{
    "customers": {
        "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 configuration file.

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

   <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:

   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 a 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.

$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. Also, the searchCriteria parameter should be used to complete the Customer Search query. See searchCriteria usage.

$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' => '*'
]);
$request->setQuery($params);

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

$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);

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

Next step

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