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:
Element | Specifies |
---|---|
HTTP verb | The action to perform against the endpoint. |
Endpoint | A combination of the server that fulfills a request, the web service, and the resource against which the request is being made. |
HTTP headers | The authentication token, the call request and response formats, and other information. |
Call 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. |
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:
HTTP header | Description | Syntax |
---|---|---|
Authorization |
Required. 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> <TOKEN> is the authentication token returned by the Magento token service. See Authentication. |
Accept |
Optional. Specifies the format of the response body. Default is JSON . |
Accept: application/<FORMAT> <FORMAT> is either JSON or XML . |
Content-Type |
Required for operations with a request body. Specifies the format of the request body. | Content-Type:application/<FORMAT> <FORMAT> is either JSON or XML . |
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.
-
Open the Magento/Customer/etc/webapi.xml
-
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>
-
Use the
method
andurl
values on theroute
element to construct the URI. In this example, the URI is POST/V1/customers
. -
Use the
class
attribute on theservice
element to identify the service interface. In this example, the service interface is theAccountManagementInterface
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 acustomer
data object. Thepassword
andredirectUrl
values are optional. The defaultpassword
value isnull
and the defaultredirectUrl
value is blank. -
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.
-
Prepare
Authorization
,Accept
andContent-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' ]);
-
Open the Magento/Customer/etc/webapi.xml configuration file and find the CustomerRepositoryInterface interface with the
getList
method. -
Set the headers, URI and method to a request object. Use URI
/V1/customers/search
and methodGET
values. Use thesearchCriteria
parameter to complete the Customer Search query. See searchCriteria usage. Also check List of REST endpoints by module.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);
-
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.