|
| 1 | +--- |
| 2 | +group: web-api |
| 3 | +title: Construct a request |
| 4 | +--- |
| 5 | + |
| 6 | +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](https://glossary.magento.com/api) calls. |
| 7 | + |
| 8 | +## Overview {#request-overview} |
| 9 | + |
| 10 | +The following table and the sections that follow the table describe [web API](https://glossary.magento.com/web-api) call elements: |
| 11 | + |
| 12 | +Element | Specifies |
| 13 | +--- | --- |
| 14 | +[HTTP verb](#verbs) | The action to perform against the endpoint. |
| 15 | +[Endpoint](#endpoints) | A combination of the _server_ that fulfills a request, the web service, and the _resource_ against which the request is being made. |
| 16 | +[HTTP headers](#http-headers) | The authentication token, the call request and response formats, and other information. |
| 17 | +[Call payload](#payload) | 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 and input attributes in a request body. You can specify a JSON- or XML-formatted request body. |
| 18 | + |
| 19 | +### HTTP verb {#verbs} |
| 20 | + |
| 21 | +Specify one of these HTTP verbs in the request: |
| 22 | + |
| 23 | +* `GET`. Requests transfer of a current representation of the target resource. If you omit the verb, `GET` is the default. |
| 24 | +* `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. |
| 25 | +* `POST`. Requests that the origin server accept the representation enclosed in the request as data to be processed by the target resource. |
| 26 | +* `DELETE`. Requests that the origin server delete the target resource. |
| 27 | + |
| 28 | +### Endpoint {#endpoints} |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | +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`. |
| 33 | + |
| 34 | +A store code can have one of the following values. |
| 35 | + |
| 36 | +* The store's assigned store code. |
| 37 | +* `default`. This is the default value when no store code is provided. |
| 38 | +* `all`. This value only applies to endpoints defined in the [CMS](https://glossary.magento.com/cms) and Product modules. If this value is specified, the [API](https://glossary.magento.com/api) call affects all of the merchant's stores. |
| 39 | + |
| 40 | +### HTTP headers {#http-headers} |
| 41 | + |
| 42 | + {:.bs-callout-info} |
| 43 | +To specify an HTTP header in a cURL command, use the `-H` option. |
| 44 | + |
| 45 | +Specify one or more of the following HTTP headers in your web API calls: |
| 46 | + |
| 47 | +HTTP header | Description | Syntax |
| 48 | +--- | --- | --- |
| 49 | +`Authorization` | Required, except for calls made on behalf of a guest. Specifies the authentication token that proves you as the owner of a Magento account. You specify the token in the `Authorization` request header with the `Bearer` HTTP authorization scheme. | `Authorization: Bearer <TOKEN>` <br/><br/>`<TOKEN>` is the authentication token returned by the Magento token service. See [Authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication.html). |
| 50 | +`Accept` | Optional. Specifies the format of the response body. Default is `JSON`. | `Accept: application/<FORMAT>` <br/><br/>`<FORMAT>` is either `JSON` or `XML`. |
| 51 | +`Content-Type` | Required for operations with a request body. Specifies the format of the request body. | `Content-Type:application/<FORMAT>` <br/><br/>`<FORMAT>` is either `JSON` or `XML`. |
| 52 | +`X-Captcha` | A shopper-entered CAPTCHA value. It is required when a shopper enters a CAPTCHA value on the frontend, unless an integration token is provided. Forms requiring CAPTCHA values are configured at **Stores** > **Configuration** > **Customers** > **Customer Configuration** > **CAPTCHA** > **Forms**. | String |
| 53 | + |
| 54 | +### Call payload {#payload} |
| 55 | + |
| 56 | +The call payload is a set of input <i>parameters</i> and <i>attributes</i> that you supply with the request. API operations have both _required_ and _optional_ inputs. |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +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: |
| 61 | + |
| 62 | +```json |
| 63 | +{ |
| 64 | + "customer": { |
| 65 | + |
| 66 | + "firstname": "John", |
| 67 | + "lastname": "Doe" |
| 68 | + }, |
| 69 | + "addresses": [ |
| 70 | + { |
| 71 | + "defaultShipping": true, |
| 72 | + "defaultBilling": true, |
| 73 | + "firstname": "John", |
| 74 | + "lastname": "Doe", |
| 75 | + "region": { |
| 76 | + "regionCode": "CA", |
| 77 | + "region": "California", |
| 78 | + "regionId": 12 |
| 79 | + }, |
| 80 | + "postcode": "90001", |
| 81 | + "street": ["Zoe Ave"], |
| 82 | + "city": "Los Angeles", |
| 83 | + "telephone": "555-000-00-00", |
| 84 | + "countryId": "US" |
| 85 | + } |
| 86 | + ] |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +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. |
| 91 | + |
| 92 | +## Construct a request {#construct-request} |
| 93 | + |
| 94 | +This example shows you how to construct a REST web API call to create an account. |
| 95 | + |
| 96 | +1. Open the [Magento/Customer/etc/webapi.xml]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Customer/etc/webapi.xml) |
| 97 | + |
| 98 | +1. Find the route element that defines the `createAccount` call: |
| 99 | + |
| 100 | + ```xml |
| 101 | + <route url="/V1/customers" method="POST"> |
| 102 | + <service class="Magento\Customer\Api\AccountManagementInterface" method="createAccount"/> |
| 103 | + <resources> |
| 104 | + <resource ref="anonymous"/> |
| 105 | + </resources> |
| 106 | + </route> |
| 107 | + ``` |
| 108 | + |
| 109 | +1. Use the <code>method</code> and `url` values on the `route` element to construct the URI. In this example, the URI is POST `/V1/customers`. |
| 110 | + |
| 111 | +1. Use the `class` attribute on the `service` element to identify the service interface. In this example, the service interface is the `AccountManagementInterface` [PHP](https://glossary.magento.com/php) file. |
| 112 | + |
| 113 | + Open the [AccountManagementInterface.php]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Customer/Api/AccountManagementInterface.php) file and find the <code>createAccount</code> method, as follows: |
| 114 | + |
| 115 | + ```php?start_inline=1 |
| 116 | + public function createAccount( |
| 117 | + \Magento\Customer\Api\Data\CustomerInterface $customer, |
| 118 | + $password = null, |
| 119 | + $redirectUrl = '' |
| 120 | + ) |
| 121 | + ``` |
| 122 | +
|
| 123 | + 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. |
| 124 | +
|
| 125 | +1. To pass the <code>customer</code> data object in the POST call payload, specify [JSON](http://www.json.com/) or [XML](https://glossary.magento.com/xml) request body on the call. |
| 126 | +
|
| 127 | +### Customers Search API request example {#customers-search-api-request-example} |
| 128 | +
|
| 129 | +The following example builds a Customers Search request based on search criteria. It returns a list of customers that match given search criteria. |
| 130 | +
|
| 131 | +1. Prepare `Authorization`, `Accept` and `Content-Type` headers to be passed to a request object. Use the [Authorization](https://glossary.magento.com/authorization) token returned by the Magento token service. |
| 132 | +
|
| 133 | + ```php?start_inline=1 |
| 134 | + $token = 'token'; |
| 135 | + $httpHeaders = new \Zend\Http\Headers(); |
| 136 | + $httpHeaders->addHeaders([ |
| 137 | + 'Authorization' => 'Bearer ' . $token, |
| 138 | + 'Accept' => 'application/json', |
| 139 | + 'Content-Type' => 'application/json' |
| 140 | + ]); |
| 141 | + ``` |
| 142 | + |
| 143 | +1. Open the [Magento/Customer/etc/webapi.xml]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Customer/etc/webapi.xml) configuration file and find the [CustomerRepositoryInterface]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Customer/Api/CustomerRepositoryInterface.php) interface with the `getList` method. |
| 144 | + |
| 145 | +1. 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]({{ page.baseurl }}/rest/performing-searches.html). |
| 146 | + |
| 147 | + The following example finds customers whose first name contains "ver" or whose last name contains "Costello". |
| 148 | + |
| 149 | + ```php?start_inline=1 |
| 150 | + $request = new \Zend\Http\Request(); |
| 151 | + $request->setHeaders($httpHeaders); |
| 152 | + $request->setUri('http://magento.ll/rest/V1/customers/search'); |
| 153 | + $request->setMethod(\Zend\Http\Request::METHOD_GET); |
| 154 | +
|
| 155 | + $params = new \Zend\Stdlib\Parameters([ |
| 156 | + 'searchCriteria' => [ |
| 157 | + 'filterGroups' => [ |
| 158 | + 0 => [ |
| 159 | + 'filters' => [ |
| 160 | + 0 => [ |
| 161 | + 'field' => 'firstname', |
| 162 | + 'value' => '%ver%', |
| 163 | + 'condition_type' => 'like' |
| 164 | + ], |
| 165 | + 1 => [ |
| 166 | + 'field' => 'lastname', |
| 167 | + 'value' => '%Costello%', |
| 168 | + 'condition_type' => 'like' |
| 169 | + ] |
| 170 | + ] |
| 171 | + ] |
| 172 | + ], |
| 173 | + 'current_page' => 1, |
| 174 | + 'page_size' => 10 |
| 175 | + ], |
| 176 | + ]); |
| 177 | +
|
| 178 | + $request->setQuery($params); |
| 179 | + ``` |
| 180 | +
|
| 181 | +1. Prepare a HTTP Curl client object and pass the request object to `Client::send()` method. |
| 182 | +
|
| 183 | + ```php?start_inline=1 |
| 184 | + $client = new \Zend\Http\Client(); |
| 185 | + $options = [ |
| 186 | + 'adapter' => 'Zend\Http\Client\Adapter\Curl', |
| 187 | + 'curloptions' => [CURLOPT_FOLLOWLOCATION => true], |
| 188 | + 'maxredirects' => 0, |
| 189 | + 'timeout' => 30 |
| 190 | + ]; |
| 191 | + $client->setOptions($options); |
| 192 | +
|
| 193 | + $response = $client->send($request); |
| 194 | + ``` |
| 195 | + |
| 196 | +This request returns a list of all customers in JSON format, as shown below. You can also specify XML format by changing <code>Accept</code> header of the request. |
| 197 | + |
| 198 | +```json |
| 199 | +{ |
| 200 | + "items": [ |
| 201 | + { |
| 202 | + "id": 1, |
| 203 | + "group_id": 1, |
| 204 | + "default_billing": "1", |
| 205 | + "default_shipping": "1", |
| 206 | + "created_at": "2017-12-05 09:50:11", |
| 207 | + "updated_at": "2018-09-22 06:32:50", |
| 208 | + "created_in": "Default Store View", |
| 209 | + "dob": "1973-12-15", |
| 210 | + |
| 211 | + "firstname": "Veronica", |
| 212 | + "lastname": "Costello", |
| 213 | + "gender": 2, |
| 214 | + "store_id": 1, |
| 215 | + "website_id": 1, |
| 216 | + "addresses": [ |
| 217 | + { |
| 218 | + "id": 1, |
| 219 | + "customer_id": 1, |
| 220 | + "region": { |
| 221 | + "region_code": "MI", |
| 222 | + "region": "Michigan", |
| 223 | + "region_id": 33 |
| 224 | + }, |
| 225 | + "region_id": 33, |
| 226 | + "country_id": "US", |
| 227 | + "street": [ |
| 228 | + "6146 Honey Bluff Parkway" |
| 229 | + ], |
| 230 | + "telephone": "(555) 229-3326", |
| 231 | + "postcode": "49628-7978", |
| 232 | + "city": "Calder", |
| 233 | + "firstname": "Veronica", |
| 234 | + "lastname": "Costello", |
| 235 | + "default_shipping": true, |
| 236 | + "default_billing": true |
| 237 | + }, |
| 238 | + { |
| 239 | + "id": 19, |
| 240 | + "customer_id": 1, |
| 241 | + "region": { |
| 242 | + "region_code": "London ", |
| 243 | + "region": "London ", |
| 244 | + "region_id": 0 |
| 245 | + }, |
| 246 | + "region_id": 0, |
| 247 | + "country_id": "GB", |
| 248 | + "street": [ |
| 249 | + "1 Studio 103 The Business Centre 61" |
| 250 | + ], |
| 251 | + "telephone": "1234567890", |
| 252 | + "postcode": "CF24 3DG", |
| 253 | + "city": "Tottenham ", |
| 254 | + "firstname": "Veronica", |
| 255 | + "lastname": "Costello" |
| 256 | + } |
| 257 | + ], |
| 258 | + "disable_auto_group_change": 0 |
| 259 | + } |
| 260 | + ], |
| 261 | + "search_criteria": { |
| 262 | + "filter_groups": [ |
| 263 | + { |
| 264 | + "filters": [ |
| 265 | + { |
| 266 | + "field": "firstname", |
| 267 | + "value": "%ver%", |
| 268 | + "condition_type": "like" |
| 269 | + } |
| 270 | + ] |
| 271 | + } |
| 272 | + ] |
| 273 | + }, |
| 274 | + "total_count": 1 |
| 275 | +} |
| 276 | +``` |
| 277 | + |
| 278 | +{:.ref-header} |
| 279 | +Related topics |
| 280 | + |
| 281 | +Run the web API call through a [cURL command]({{ page.baseurl }}/get-started/gs-curl.html) or a REST client. |
0 commit comments