Table of Contents
- Introduction to API
- Overall Capabilities
- Output Formats
- HTTP Verbs
- Request Structure
- REST Resources
- Preparing for REST API
- Preparing REST API for the Third-Party Application
- PHP Examples
- REST Client Example
What is REST API? To make it simple, REST API defines a set of functions to which the developers can perform requests and receive responses. The interaction is performed via the HTTP protocol. An advantage of such an approach is the wide usage of HTTP. That is why REST API can be used practically for any programming language.
Common characteristics of Magento REST API resources are as follows: (magentohost is your domain)
- You access the resource by sending an HTTP request to the Magento API server. The server replies with a response that contains either the data you requested, or the status indicator, or even both.
- All resources are located at https://magentohost/api/rest/.
- All resources may return different HTTP status codes (e.g., HTTP Status Code 200 for success response or HTTP Status Code 400 for the bad request).
- You request a particular resource by adding a particular path to the base URL that specifies the resource.
Magento REST API allows managing a number of features, namely:
- Managing customers.
- Managing customer addresses.
- Managing products.
- Retrieving sales orders.
- Managing inventory.
Magento REST API uses 3-legged OAuth 1.0a protocol to authenticate the application to access the Magento service.
The REST API supports the response in two formats, which are XML and JSON.
HTTP verbs are used to manage the state of resources. In Magento REST API, there are four verbs used to manage resources: GET, POST, PUT, and DELETE. You can get the contents of the data using HTTP GET, delete the data using HTTP DELETE, and create or update the data using POST/PUT.
All URLs in REST API have the following base URL.
Supposing, you want to retrieve the list of customers from Magento. To do this, you need to use the GET HTTP method. The GET request to retrieve the list of customers will look as follows:
- http://magentohost/api/rest/ - endpoint
- /customers - action URL
The Magento REST API allows you to manage customers, customer addresses, sales orders, inventory, and products. REST API is organized into the following categories:
- Retrieve the list of products, create, update, and delete a product.
Resource Structure: http://magentohost/api/rest/products
- Retrieve the list of categories assigned to a product, assign, and unassign the category to/from the specific product.
Resource Structure: http://magentohost/api/rest/products/:productId/categories
- Retrieve the list of images assigned to a product, add, update, and remove an image to/from the specific product.
Resource Structure: http://magentohost/api/rest/products/:productId/images
- Retrieve the list of websites assigned to a product, assign, and unassign a website to/from the specific product.
Resource Structure: http://magentohost/api/rest/products/:productId/websites
- Retrieve the list of customers, create, delete a customer, and update the customer information.
Resource Structure: http://magentohost/api/rest/customers
- Retrieve the list of customer addresses, create, update, and delete the customer address.
Resource Structure: http://magentohost/api/rest/customers/:customerId/addresses
- Retrieve the list of stock items and update required stock items.
Resource Structure: http://magentohost/api/rest/stockitems
- Retrieve the list of sales orders as well as the specific order information.
Resource Structure: http://magentohost/api/rest/orders
- Retrieve order items for the specific order.
Resource Structure: http://magentohost/api/rest/orders/:orderId/items
- Retrieve information on order billing and shipping addresses for the specific order.
Resource Structure: http://magentohost/api/rest/orders/:orderId/addresses
- Retrieve order comments for the specific order
Resource Structure: http://magentohost/api/rest/orders/:orderId/comments
These steps are required for utilizing REST API resources:
- Set up permissions for REST resource operations from Magento Admin Panel.
- Configure the attributes for different users types in Magento Admin Panel. There are 3 different types of users in accessing the data: Admin, Customer, and Guest. Admin is the backend logged in user, Customer is the fronted logged in user, and Guest is a non-logged in fronted user.
- Register the third-party application (Consumer) in Magento Admin Panel.
- The third-party application will utilize the provided consumer credentials to call Magento store for getting the access token to access the data.
Retrieving the list of Products as a Guest
- Use the REST Client that is a FireFox add-on. In the REST Client, in the Method drop-down list, select the GET option.
- In the URL field, enter the following URL: http://magentohost/api/rest/products?limit=2.
- Click Send. Information about the products will be displayed in the response body. Example in the XML format is as follows:
You can define the limit of items returned in the response by passing the limit parameter. By default, 10 items are returned and the maximum number is 100 items. You can also define the page number by passing the page parameter. Example:
Authorization header will be required for Admin and Customer user types. The following parameters must be provided in the Authorization header for the call:
- oauth_consumer_key - the Consumer Key value provided after the registration of the application.
- oauth_nonce - a random value, uniquely generated by the application.
- oauth_signature_method - name of the signature method used to sign the request. Can have one of the following values: HMAC-SHA1, RSA-SHA1, and PLAINTEXT.
- oauth_signature - a generated value (signature).
- oauth_timestamp - a positive integer, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
- oauth_token - the oauth_token value (Request Token).
- oauth_version - OAuth version.