Magento Rest API

I started a project to extend the Imixs-Workflow Project with a Magento Plugin to exchange order data from the Magento Platform with the Imixs Workflow Engine running in a Java Enterprise Server. In the following section I post some of my experiences. Magento Community Edition provides since Version 1.7.0 a Rest API for an easy access to all the business data managed by Magento shop solutions. An overview about the capabilities of the Rest API can be found here. There is also a short tutorial showing how to test the Rest API with a Browser Plugin in Firefox or Chromium. See also the Magento Forum at stackexchange for questions and answers.

Rest API returns 404

I installed Magento first on my local developer machine (Linux Debian 64Bit).  My test shop is available on my local host at:

http://localhost/magento

The Rest API URL to fetch all products should look like this:

http://localhost/magento/api/rest/products

Starting with my first tests I recognized that each test returns an Http Error 404.

To fix this issue check first the apache configuration (/etc/apache2/apache2.conf). There you need to add the following section to enable the rewrite feature which is needed by Magento:

<Directory /var/www/html/magento/>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
</Directory>

Be careful with the directory path in the Tag ‘Directory’. The path must match the location of your Magento installation on the file system. After changing the configuration restart the apache server.

/etc/init.d/apache2 restart

Enable server rewrites

If you know that server rewrites are enabled you can skip this step. Enabling server rewrites allows for index.php to be removed from all urls. To check or to enable server rewrites open the apache default configuration file:

sudo vi /etc/apache2/sites-available/default

Make sure that AllowOverride is set to All and not None for /var/www/ portion of the code, which should look like this:

<Directory /var/www/>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride All
    Order allow,deny
    allow from all
</Directory>

Next you also need to make sure that the rewrite module is actually enabled. To check, list the content of /etc/apache2/mods-enabled, where if you don’t find a link called rewrite.load you then need to create one. To create it, type:

cd /etc/apache2/mods-enabled
sudo ln -s ../mods-available/rewrite.load

You will now need to restart Apache for all of these changes to take effect. Server rewrites should now be enabled.

Rest API returns 401

If your Rest API returns http error 401 when trying to authenticat with OAuth, this can be a hint for a problem with the port. Magento OAuth did not work on port numbers other then port 80. You will see a error message like this:

Invalid auth/bad request (got a 401, expected HTTP/1.1 20X or a redirect)
oauth_problem=signature_invalid&debug_sbs=7v74k3sMtbLNtOm36OFZVvMy9SY=

See also here.

Installing OAuth for PHP clients

If you want to use the OAuth mechanism in a PHP program it is necessary to install the pecl OAuth extension. I will explain the installation in this section:

Before you begin, create a phpinfo.php file, if you have not already done so, to determine if you already have OAuth running. Create a file named phpinfo.php anywhere on the web server’s docroot:

<?php
// Show all information, defaults to INFO_ALL
phpinfo();

Start a web browser and enter the following URL in its address or location field:

http://host-or-ip[:port]/path-to-phpinfo/phpinfo.php

Search the resulting output for OAuth.
The following figure shows an example of OAuth being properly set up.

If the preceding does not display, OAuth is not set up so you need to install the OAuth packages first.

Installing the OAuth Packages

The OAuth extension requires both PEAR (which enables you to install the package) and libpcre3-dev, which enables the OAuth package to be compiled. To install the packages and confirm that OAuth is enabled, enter the following commands in the order shown:

apt-get install php-pear
apt-get install libpcre3-dev
pecl install oauth

If the following displays, you must edit your php.ini file to find the OAuth library:

    configuration option “php_ini” is not set to php.ini location
    You should add “extension=oauth.so” to php.ini

Open php.ini in a text editor (location in /etc/php5/apache2/) and add the following anywhere in php.ini:

    [OAuth]
    extension=oauth.so

Save your changes to php.ini and restart the Apache web server.
Now check again if that OAuth is Installed Successfully.

 

How to work with Magento Rest API

To acitvate the Magento Rest API you need to add some roles. First register a new consumer : System -> Web Service -> REST OAuth Consumers

Next create a new Admin Role called ‘Administrator’ :
System -> Web Service – REST OAuth Roles
and assign the required API Resources to that role.

Finally you can assign this new Role to one of the registered Magento users :
System -> Permissions – > Users – > REST Roles

Access Magento from Java

To access the Magento Rest API from java I recommend to use java-scribe. This small library makes it easy to do the OAuth stuff which is necessary to access the Magento api.

You can find an tutorial how to use it here.

The JSON Format

The json format provided by Magento is straight forward. A List of items has the following format:

[
    {
        "item_id":"1",
        "product_id":"1",
        "stock_id":"1",
        ...
    },
    {
        "item_id":"2",
        "product_id":"2",
        "stock_id":"1",
    ...
    }
]

Lists are stored in arrays or in some cases in a kind of ordered list. In this case the format looks like this:

{
    "1":{
        "entity_id":"1",
        "attribute_set_id":"4",
        "type_id":"simple",
    ...
    },
    "2":{
        "entity_id":"2",
        "attribute_set_id":"4",
        "type_id":"simple",
    ....
    }
}

Both formats can be easily pared with the Java javax.json.Json Parser. You can find the Parser developed for the Imixs Magento Adapter here.

 Post data to Magento

Using the Rest API from Magento it is also possible to post back data to the magento shop system. This works for product data and customer data. But – and this is realy an amiss – it is not possible for order data. So you have currently no chance to control the order data of Magento from an external system using the Magento Rest API.