The web service

The web service is the shop's built-in API. Through it external programs — a warehouse system, a mobile app, an export script — read and change products, orders and customers with HTTP requests, without access to the database. No code has to be written in the shop for that: the API is already there and only needs to be enabled.

Enabling

1. Open "Advanced Parameters → Webservice" in the back office.
2. Turn on the "Enable PrestaShop's webservice" switch and save.
3. Press "Add new webservice key".
4. Press "Generate" — you get a key of 32 characters.
5. In the permissions table tick what the key may do: for example GET for products and orders.
6. Save.

A key is a password to the shop's data. Give every program its own key and only the permissions it needs.

The first request

The API is available at /api. The key is passed as the user name of ordinary HTTP authentication, and the password is left empty:

curl -u YOUR_KEY: "http://shop.test/api/products?output_format=JSON"

The response is a list of product ids:

{
    "products": [
        { "id": 1 },
        { "id": 2 }
    ]
}

Without the output_format=JSON parameter the response comes in XML — the default format.

Resources

Every kind of data is a resource with its own address. A request to /api itself shows the list of resources available to the key.

One record

curl -u YOUR_KEY: "http://shop.test/api/products/1?output_format=JSON"

The request returns all fields of product number 1: the price, the reference, the names in all languages, the ids of related categories and images.

Filtering and fields

A list is tuned with request parameters.

curl -g -u YOUR_KEY: "http://shop.test/api/products?output_format=JSON&display=[id,name,price]&filter[active]=[1]&limit=5"

The request returns five enabled products with three fields each. The -g option stops curl from interpreting the square brackets in its own way.

HTTP methods

Creating and changing

Data for writing is sent in XML. The schema=blank parameter gives an empty skeleton with all fields of a resource:

curl -u YOUR_KEY: "http://shop.test/api/customers?schema=blank"

The skeleton is filled in and sent with the POST method to the resource address:

curl -u YOUR_KEY: -X POST -H "Content-Type: text/xml" \
    --data-binary @customer.xml "http://shop.test/api/customers"

The response is the created record with its id. To change a record, send the full record with the PUT method to the address with the id, for example /api/customers/5.

Changing an order status

A frequent task of a warehouse system is to mark an order as shipped. For that you do not change the order itself but create a record in the order_histories resource with the order id and the id of the new status. The shop then behaves the same way as when the status is changed in the back office: it calls hooks and sends an email to the customer.

Your own data

Module tables do not appear in the API by themselves. A module can add its own resource with the addWebserviceResources hook and a webserviceParameters description in the model class. If you need one or two simple addresses, it is easier to write a front controller that answers with JSON, as in the lesson on forms and AJAX.

Common mistake

A request returns 401 although the key is correct. On many Apache servers with PHP in CGI or FPM mode the authorization header does not reach PHP. Check that the shop's .htaccess file has a rule that passes HTTP_AUTHORIZATION — it is created when friendly URLs are enabled — or pass the key in the ws_key address parameter while testing.