Magento API

REST

About Magento API

Introduction to API

Overview

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.

Overall Capabilities

Magento REST API allows managing a number of features, namely:

  • Managing customers.
  • Managing customer addresses.
  • Managing products.
  • Retrieving sales orders.
  • Managing inventory.

Authentication

Magento REST API uses 3-legged OAuth 1.0a protocol to authenticate the application to access the Magento service.

Output Formats

The REST API supports the response in two formats, which are XML and JSON.

HTTP Verbs

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.

Request Structure

All URLs in REST API have the following base URL. 

http://magentohost/api/rest/

Example

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:

where

REST Resources

The Magento REST API allows you to manage customers, customer addresses, sales orders, inventory, and products. REST API is organized into the following categories:

Products
Product Categories
Product Images
Product Websites
Customers
Customer Addresses
Inventory
Sales Orders
Order Items
Order Addresses
Order Comments

Preparing for REST API

These steps are required for utilizing REST API resources:

  1. Set up permissions for REST resource operations from Magento Admin Panel.
  2. 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.

Preparing REST API for the Third-Party Application

  1. Register the third-party application (Consumer) in Magento Admin Panel.
  2. The third-party application will utilize the provided consumer credentials to call Magento store for getting the access token to access the data.

PHP Examples

Create a simple product as an Admin user with OAuth authentication

<?php
/**
* Example of simple product POST using Admin account via Magento REST API. OAuth authorization is used
*/
$callbackUrl = "http://yourhost/oauth_admin.php";
$temporaryCredentialsRequestUrl = "http://magentohost/oauth/initiate?oauth_callback=" . urlencode($callbackUrl);
$adminAuthorizationUrl = 'http://magentohost/admin/oauth_authorize';
$accessTokenRequestUrl = 'http://magentohost/oauth/token';
$apiUrl = 'http://magentohost/api/rest';
$consumerKey = 'yourconsumerkey';
$consumerSecret = 'yourconsumersecret';

session_start();
if (!isset($_GET['oauth_token']) && isset($_SESSION['state']) && $_SESSION['state'] == 1) {
    $_SESSION['state'] = 0;
}
try {
    $authType = ($_SESSION['state'] == 2) ? OAUTH_AUTH_TYPE_AUTHORIZATION : OAUTH_AUTH_TYPE_URI;
    $oauthClient = new OAuth($consumerKey, $consumerSecret, OAUTH_SIG_METHOD_HMACSHA1, $authType);
    $oauthClient->enableDebug();

    if (!isset($_GET['oauth_token']) && !$_SESSION['state']) {
        $requestToken = $oauthClient->getRequestToken($temporaryCredentialsRequestUrl);
        $_SESSION['secret'] = $requestToken['oauth_token_secret'];
        $_SESSION['state'] = 1;
        header('Location: ' . $adminAuthorizationUrl . '?oauth_token=' . $requestToken['oauth_token']);
        exit;
    } else if ($_SESSION['state'] == 1) {
        $oauthClient->setToken($_GET['oauth_token'], $_SESSION['secret']);
        $accessToken = $oauthClient->getAccessToken($accessTokenRequestUrl);
        $_SESSION['state'] = 2;
        $_SESSION['token'] = $accessToken['oauth_token'];
        $_SESSION['secret'] = $accessToken['oauth_token_secret'];
        header('Location: ' . $callbackUrl);
        exit;
    } else {
        $oauthClient->setToken($_SESSION['token'], $_SESSION['secret']);
        $resourceUrl = "$apiUrl/products";
        $productData = json_encode(array(
            'type_id'           => 'simple',
            'attribute_set_id'  => 4,
            'sku'               => 'simple' . uniqid(),
            'weight'            => 1,
            'status'            => 1,
            'visibility'        => 4,
            'name'              => 'Simple Product',
            'description'       => 'Simple Description',
            'short_description' => 'Simple Short Description',
            'price'             => 99.95,
            'tax_class_id'      => 0,
        ));
        $headers = array('Content-Type' => 'application/json');
        $oauthClient->fetch($resourceUrl, $productData, OAUTH_HTTP_METHOD_POST, $headers);
        print_r($oauthClient->getLastResponseInfo());
    }
} catch (OAuthException $e) {
    print_r($e);
}

Retrieve the list of products as a Customer user with OAuth authentication

<?php
/**
 * Example of products list retrieve using Customer account via Magento REST API. OAuth authorization is used
 */
$callbackUrl = "http://yourhost/oauth_customer.php";
$temporaryCredentialsRequestUrl = "http://magentohost/oauth/initiate?oauth_callback=" . urlencode($callbackUrl);
$adminAuthorizationUrl = 'http://magentohost/oauth/authorize';
$accessTokenRequestUrl = 'http://magentohost/oauth/token';
$apiUrl = 'http://magentohost/api/rest';
$consumerKey = 'yourconsumerkey';
$consumerSecret = 'yourconsumersecret';

session_start();
if (!isset($_GET['oauth_token']) && isset($_SESSION['state']) && $_SESSION['state'] == 1) {
    $_SESSION['state'] = 0;
}
try {
    $authType = ($_SESSION['state'] == 2) ? OAUTH_AUTH_TYPE_AUTHORIZATION : OAUTH_AUTH_TYPE_URI;
    $oauthClient = new OAuth($consumerKey, $consumerSecret, OAUTH_SIG_METHOD_HMACSHA1, $authType);
    $oauthClient->enableDebug();

    if (!isset($_GET['oauth_token']) && !$_SESSION['state']) {
        $requestToken = $oauthClient->getRequestToken($temporaryCredentialsRequestUrl);
        $_SESSION['secret'] = $requestToken['oauth_token_secret'];
        $_SESSION['state'] = 1;
        header('Location: ' . $adminAuthorizationUrl . '?oauth_token=' . $requestToken['oauth_token']);
        exit;
    } else if ($_SESSION['state'] == 1) {
        $oauthClient->setToken($_GET['oauth_token'], $_SESSION['secret']);
        $accessToken = $oauthClient->getAccessToken($accessTokenRequestUrl);
        $_SESSION['state'] = 2;
        $_SESSION['token'] = $accessToken['oauth_token'];
        $_SESSION['secret'] = $accessToken['oauth_token_secret'];
        header('Location: ' . $callbackUrl);
        exit;
    } else {
        $oauthClient->setToken($_SESSION['token'], $_SESSION['secret']);
        $resourceUrl = "$apiUrl/products";
        $oauthClient->fetch($resourceUrl);
        $productsList = json_decode($oauthClient->getLastResponse());
        print_r($productsList);
    }
} catch (OAuthException $e) {
    print_r($e);
}

REST Client Example

Retrieving the list of Products as a Guest

  1. Use the REST Client that is a FireFox add-on. In the REST Client, in the Method drop-down list, select the GET option.
  2. In the URL field, enter the following URL: http://magentohost/api/rest/products?limit=2.
  3. Click Send. Information about the products will be displayed in the response body. Example in the XML format is as follows:

Example: XML

<?xml version="1.0"?>
<magento_api>
  <data_item>
    <entity_id>16</entity_id>
    <type_id>simple</type_id>
    <sku>n2610</sku>
    <description>The Nokia 2610 is an easy to use device that combines multiple messaging options including email, instant messaging, and more. You can even download MP3 ringtones, graphics, and games straight to the phone, or surf the Internet with Cingular's MEdia Net service. It's the perfect complement to Cingular service for those even remotely interested in mobile Web capabilities in an affordable handset.
Design
Compact and stylish, the 2610 features a candybar design sporting a bright 128 x 128 pixel display capable of displaying over 65,000 colors. Most of the phone's features and on-screen menus are controlled by a center toggle on the control pad. A standard hands-free headphone jack is provided, as are volume control keys, and there's even a "Go-To" button that can be assigned by the user for quick access to favorite applications. Lastly, the included speakerphone allows you to talk handsfree, and because the phone sports an internal antenna, there's nothing to snag or break off.
</description>
    <meta_keyword>Nokia 2610, cell, phone, </meta_keyword>
    <short_description>The words "entry level" no longer mean "low-end," especially when it comes to the Nokia 2610. Offering advanced media and calling features without breaking the bank</short_description>
    <name>Nokia 2610 Phone</name>
    <meta_title>Nokia 2610</meta_title>
    <meta_description>Offering advanced media and calling features without breaking the bank, The Nokia 2610 is an easy to use</meta_description>
    <regular_price_with_tax>149.99</regular_price_with_tax>
    <regular_price_without_tax>149.99</regular_price_without_tax>
    <final_price_with_tax>149.99</final_price_with_tax>
    <final_price_without_tax>149.99</final_price_without_tax>
    <is_saleable>1</is_saleable>
    <image_url>http://magentohost/imageulr/nokia.jpg</image_url>
  </data_item>
  <data_item>
    <entity_id>17</entity_id>
    <type_id>simple</type_id>
    <sku>bb8100</sku>
    <description> Like the BlackBerry 7105t, the BlackBerry 8100 Pearl is
The BlackBerry 8100 Pearl sports a large 240 x 260 screen that supports over 65,000 colors-- plenty of real estate to view your e-mails, Web browser content, messaging sessions, and attachments. The venerable BlackBerry trackwheel has been replaced on this model with an innovative four-way trackball placed below the screen. On the rear of the handheld, you'll find a 1.3-megapixel camera and a self portrait mirror. The handheld's microSD memory card slot is located inside the device, behind the battery. There's also a standard 2.5mm headset jack that can be used with the included headset, as well as a mini-USB port for data connectivity.</description>
    <meta_keyword>Blackberry, 8100, pearl, cell, phone</meta_keyword>
    <short_description>The BlackBerry 8100 Pearl is a departure from the form factor of previous BlackBerry devices. This BlackBerry handset is far more phone-like, and RIM's engineers have managed to fit a QWERTY keyboard onto the handset's slim frame.</short_description>
    <name>BlackBerry 8100 Pearl</name>
    <meta_title>BlackBerry 8100 Pearl</meta_title>
    <meta_description>BlackBerry 8100 Pearl sports a large 240 x 260 screen that supports over 65,000 colors-- plenty of real estate to view your e-mails, Web browser content, messaging sessions, and attachments.</meta_description>
    <regular_price_with_tax>349.99</regular_price_with_tax>
    <regular_price_without_tax>349.99</regular_price_without_tax>
    <final_price_with_tax>349.99</final_price_with_tax>
    <final_price_without_tax>349.99</final_price_without_tax>
    <is_saleable>1</is_saleable>
    <image_url>http://magentohost/imageulr/blackberry.jpg</image_url>
  </data_item>
</magento_api>

Additional Information

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.