API:
Is RESTful
Uses Basic HTTP authentication, with admin e-mail as login and auto-generated API key as password
Relies on user group-defined privileges. User group assignment is defined directly in the objects
Uses HTTP 1.1 to implement REST.
4 methods are available to view and modify objects:
GET—get object data
PUT—update object data
POST—create new object
DELETE—delete object
Accepts and returns data in JSON format
cURL is a cross-platform command line application that allows you to easily send HTTP requests. In UNIX-based systems, it is usually available by default with a simple curl command.
Note
All examples in this guide are given as cURL commands.
Postman is an extension for the popular Google Chrome browser. Similar extensions exist for all popular web-browsers.
API access is activated/disabled on a per-user basis.
To activate API access for a user:
Log in to admin panel
Go to Customers → Administrators
Open the admin account you want to activate API access to (e.g. admin@example.com)
Switch to the API access tab and check the Yes, allow this user to use the API box
Click Save
The automatically generated API key will be used by this user along with their e-mail to access the API.
An API request is a regular HTTP request sent to a particular URL.
By default, uses API 1.0 with the URLs built as follows:
http://example.com/api/:object—refer to all objects of a certain type
http://example.com/api/:object/:id—refer to a single object
http://example.com/api/:object/:id/:nested_object:—refer to all nested objects of a certain object
http://example.com/api/:object/:id/:nested_object/:id—refer to a single nested object of a certain object
For example, http://example.com/api/product/1/features refers to all the features of the product with the ID 1.
Note
If mod_rewrite is disabled on the server where the target store is installed, you will have to use different URLs:
http://example.com/api.php?_d=:object&ajax_custom=1—refer to all objects of a certain type
http://example.com/api.php?_d=:object/:id&ajax_custom=1—refer to a single object
http://example.com/api.php?_d=:object/:id/:nested_object&ajax_custom=1—refer to all nested objects of a certain object
http://example.com/api.php?_d=:object/:id/:nested_object/:id&ajax_custom=1—refer to a single nested object of a certain object
Nonetheless, API 2.0 is recommended. In API 2.0 the URLs have the following structure:
http://example.com/api/2.0/:object—refer to all objects of a certain type
http://example.com/api/2.0/:object/:id—refer to a single object
http://example.com/api/2.0/:object/:id/:nested_object:—refer to all nested objects of a certain object
http://example.com/api/2.0/:object/:id/:nested_object/:id—refer to a single nested object of a certain object
Each request must be authenticated with user’s e-mail and API key. There are 3 ways to submit authentication data in an API request:
Via the --user parameter (this is used in all the examples):
curl --user admin@example.com:APIkey -X GET 'http://example.com/api/users/'
Inline passing in the URL:
curl --basic -X GET 'http://admin%40example.com:APIkey@example.com/api/users/'
Note
@ must be replaced with %40
In the request header:
curl --header 'Authorization: Basic <base64-encoded email:APIkey pair>=' -X GET 'http://example.com/api/users/'
Note
The email:APIkey pair must be encoded in base64.
PHP example:
$token = base64_encode("email:APIkey");
$authHeaderString = 'Authorization: Basic ' . $token;
GET)¶To get object data, send a GET HTTP request to the URL that refers to the according object.
Get data about the product with the ID 1:
curl --user admin@example.com:APIkey -X GET 'http://example.com/api/products/1'
It is possible to send additional URL parameters to particularize the selection.
For example, you get all products with non-free shipping:
curl --user admin@example.com:APIkey -X GET 'http://example.com/api/products?free_shipping=N'
You can combine conditions.
Get all downloadable products with company_id 1:
curl --user admin@example.com:APIkey -X GET 'http://example.com/api/products?is_edp=Y&company_id=1'
JSON array of matching objects (e.g. the products key) and the search query (the search key), or an error.
The matching objects value is an array of object IDs as keys and object field arrays as values.
Refer to the API objects page for a complete list of supported fields for all supported objects.
PUT)¶To update object data, send a PUT HTTP request to the URL that refers to the according object.
Only URLs referring to particular object IDs can be used (i.e. you cannot update all products at once.)
The submitted data must be a JSON array of keys and values for the object fields (e.g. {'fieldName1: value1, fieldName2: value2}.)
Refer to the API objects page for a complete list of supported fields for all supported objects.
Important
The header Content-Type must be declared and set to application/json, otherwise the default text/plain is assumed and the request will fail.
Update name of the product with the ID 1:
curl --user admin@example.com:APIkey --header 'Content-Type: application/json' -d '{"product": "New Product Name"}' -X PUT 'http://example.com/api/products/1'
Updated object ID, e.g. {"product_id":"1"}, or an error.
POST)¶To create an object, send a POST HTTP request to the URL that refers to the according object type.
Only URLs referring to a whole object type (without ID) can be used.
The submitted data must be a JSON array of keys and values for the object fields (e.g. {'fieldName1: value1, fieldName2: value2}.)
Some fields are mandatory for object creating. Refer to the API objects page for a complete list of supported fields for all supported objects.
Important
The header Content-Type must be declared and set to application/json, otherwise the default text/plain is assumed and the request will fail.
Create a new product with the name “My Awesome Product”:
curl --user admin@example.com:APIkey --header 'Content-Type: application/json' -d '{"product": "My Awesome Product"}' -X POST 'http://example.com/api/products'
Created object ID, e.g. {"product_id":"1"}, or an error.
DELETE)¶To delete an object, send a DELETE HTTP request to the URL that refers to the according object.
Only URLs referring to particular object IDs can be used (i.e. you cannot delete all products at once.)
Delete the product with the id 12:
curl --user admin@example.com:APIkey -X DELETE 'http://example.com/api/products/12'
204 response with empty body.