REST API v2.8

Quick Start

Sitoo REST API makes it easy for developers to create, read, update, delete resources in Sitoo. The REST standard also makes it easy and intuitive to use the API. If you aren't familiar with REST, please check out the many tutorials available on the Internet.

Rest API

The REST API uses standard HTTP methods for the four different operations you can make on a resource namely: GET to read a resource, POST to add a resource, PUT to update a resource and DELETE to delete a resource. All major programming languages including PHP, Python, Ruby, Java and C# have libraries for sending a HTTP request and handle the response. Sending and receiving data is done using JSON.

You can use cURL for testing.

curl -i \
-X POST \
-H "Content-Type: application/json" \
-u "{API ID}:{password}" \
-H "Accept: application/json" \
-d '{ "value": 25, "productgrouptype": 20, "productgroupname": "Shoes", "comment": "All shoes" }' \
-s "https://api.mysitoo.com/v2/accounts/{accountid}/sites/1/productgroups.json"

Authentication

Authentication is done with the HTTP basic authentication mechanism over a secure connection. The API ID and password can be found in the Backoffice under settings/Sitoo REST API (requires Administrator privileges and that the API extension has been added to the system).

With the API ID and password, add an extra header to the request for authentication:

"Authorization: Basic " + base64_encode("{API ID}" + ":" + "{password}");

Example header (API ID "10020-140" and password "buNxoOx2o5kM2JMc3VhBX20k4Gik4qKXyKfg332A"):

Authorization: Basic MTAwMjAtMTQwOmJ1TnhvT3gybzVrTTJKTWMzVmhCWDIwazRHaWs0cUtYeUtmZzMzMkE=)

Note that the request must originate from an allowed ip (which is defined in the Backoffice), otherwise the request will be rejected.

JSON format

Sitoo REST API uses JSON format for request and response bodies. The response mime-type is "application/json".

Retrieving collections and envelopes

A collection is returned in an envelope. The envelope contains the total count of items the query could return and an array of items actually returned. This makes it easy to create a pagination when used with the start and num parameters. Example:

Request

GET https://api.mysitoo.com/v2/accounts/1500/sites/1/products.json?start=2&num=2&fields=productid,sku,title,moneyprice

Response

{
    "totalcount": 15,
    "items": [
        {
            "productid": 12,
            "sku": "10038-1",
            "moneyprice": "10392.00",
            "title": "Sofa Grand III"
        },
        {
            "productid": 13,
            "sku": "10038-5",
            "moneyprice": "10392.00",
            "title": "Kitchen Table"
        }
    ]
}

Totalcount is 15 and the items array contains the two items from index 2 (zerobased).

Speed things up

Only ask for data that you will use. This speeds up the transfer of data and makes the underlying database query faster. Use the fields parameter to specify which fields to have returned. Specifying fields is key to speed things up.

Some endpoints also have batch operations enabled. Batch operations allows you to send multiple objects at once. The batch operation is a shortcut for sending many objects at a time (ie. it is not a transaction were all fail or succeed). A batch envelope is returned and for every object in the request there will be an individual result.

Response

PUT https://api.mysitoo.com/v2/accounts/1500/sites/1/products.json [ { "productid": 12, "moneyprice": "990.00" }, { "productid": 13, "moneyprice": "1290.00" } ]

Response with a batch envelope

[ { "statuscode": 200, "return": true }, { "statuscode": 200, "return": true } ]

POST and PUT data

To add or update resources send a JSON object containing the properties in the request body. For example:

{"sku":"123456","moneyprice":"990.00"}

Rate limits

You're only allowed to make a fixed number of requests per time slot (currently 10 min). This makes it important to choose the correct way to use the API. Instead of updating products one-by-one, use batch operations (ie. send an array with all changes at once).

When the rate limit is exceeded then a "429 Too Many Requests" will be returned.

Response headers are added

X-Rate-Limit-Limit: 500
X-Rate-Limit-Remaining: 489
X-Rate-Limit-Reset: 422

X-Rate-Limit-Max is the maximum number of requests allowed within a time slot
X-Rate-Limit-Remaining is the number of requests left within the current time slot
X-Rate-Limit-Reset is the number of seconds left of the current time slot (ie. before the rate limit is reset)