...
Table of Contents | ||
---|---|---|
|
Webservice one-page documentation
This chapter aims at grouping all the information from the webservice tutorial into a handy one-page doc that you can print and keep at hand.
Setting everything up
In order for you to view, edit and delete the data on your PrestaShop store through its webservice, you first need to enable the webservice feature, and then create an access key.
Enabling cURL
Configure your PHP installation so that it has the cURL extension installed and enabled:
...
Code Block |
---|
sudo apt-get install php5-curl |
Enabling the webservice feature
Go in the PrestaShop back-office, open the "Webservice" page under the "Advanced Parameters" menu, and then choose "Yes" for the "Enable PrestaShop's webservice". Save your change: you're done!
Creating an access key
Open the "Webservice" page under the "Advanced Parameters" menu, and then click the "Add New" button to access the account configuration section. A long form appears:
...
If you choose to use a custom passkey instead of a generated one, make sure it is very secure and that its rights are limited – and that it is 32characters long!
Accessing the webservice from the browser
The endpoint to your store's webservice is located in the /api/
folder at the root of your installation of Prestashop:
...
You can either type the API endpoint address directly then enter your API key, or indicate your API key in the address. Here is an example, with "UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX" being the API key.
- Root At the root of the server: http://[email protected]/api/
- Subfolder In a subfolder of the server: http://[email protected]/prestasshop/api/
...
Using XLink, you will then be able to access your various resources. XLink associates an XML file to another XML file via a link.
Accessing the webservice
...
use our PHP library
You will need the latest version of the PSWebServiceLibrary.php
file, which can be found on our code repository: https://github.com/PrestaShop/PrestaShop-webservice-lib/blob/master/PSWebServiceLibrary.php
To download the file:
...
Code Block |
---|
$webService = new PrestaShopWebservice('http://example.com/', 'UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX', false); |
Handling errors
It is essential that you understand how to handle errors with the webservice library. By implementing error-catch method early, you will more easily detect issues, and be able to correct them on the go.
Error handling with the webservice library is done using PHP exceptions. If you do not know about them, you should read http://php.net/manual/en/language.exceptions.php, as exceptions are an essential part of good coding practice.
How it works
The error handling is done within a try..catch
block, with the webservice processing being done in the try section, the catch one containing the error handling code.
Code Block |
---|
try { // Execution ( if an error occurs in this code, stops and goes in the catch block) } catch { // Error handling (tries to catch the error or the error display) } |
Example
That means each creation or use of the library must be located within a "try" block. The "catch" block can then handle the error if it occurs during the execution of the try block.
Now we'll see how to list all customers via the webservice, and then we will see the four CRUD methods.
...
Code Block |
---|
try { // creating webservice access $webService = new PrestaShopWebservice('http://example.com/', 'UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX', false); // call to retrieve all clients $xml = $webService->get(array('resource' => 'customers')); } catch (PrestaShopWebserviceException $ex) { // Shows a message related to the error echo 'Other error: <br />' . $ex->getMessage(); } |
Examples files
All the example files can be found on our code repository: https://github.com/PrestaShop/PrestaShop-webservice-lib/tree/master/examples
Working with your data
As shown above, you have to instantiate the PrestaShopWebservice
object in order to use its methods: add()
, get()
, edit()
and delete()
.
You can also directly use call the REST API and get XML results, as this correspondence table shows:
CRUD operations | SQL statements | PrestaShopWebservice methods | HTTP methods |
---|---|---|---|
Create | INSERT | add() | POST |
Read | SELECT | get() | GET |
Update | UPDATE | edit() | PUT |
Delete | DELETE | delete() | DELETE |
...
Viewing your data
Using the PrestaShopWebservice methods
Let's see how to view a full list of client IDs. As you can see from the table above, we need the get()
method in order to retrieve a XML file containing all the customers. The parameter has to be a key-value array, where we define the resource we want:
...
The value defines the resource that the webservice will use in a future call. The value could be carrier types, countries or any other type of resource that can be found in the "Available resources" section of this guide.
The code
In order to retrieve a list of customers in XML format, you only need to instantiate PrestaShopWebservice
(a seen earlier) and use this code:
Code Block |
---|
// The key-value array $opt['resource'] = 'customers'; Retrieving the XML data $xml = $webService->get($opt); |
The result
Launching the code above will return a XML object containing all the current customer IDs on the store:
...
Code Block |
---|
$opt['resource'] = 'customers'; $opt['id'] = 1; $xml = $webService->get($opt); |
Structure
As you can see in the result in the previous section, the data returned by calling $webService->get()
puts you at the root of the XML document, in the context you requested.
...
Thanks to these elements, you can create a HTML table containing all the client IDs – or anything that displays this information in your interface.
Using HTTP requests
If you would rather not use the PrestaShopWebservice
object, note that PrestaShop's webservice is RESTful, in that you can work with its data using the known HTTP verbs just as easily as you would use the methods of the PrestaShopWebservice
object.
...
The resulting XML document is the same as the one obtained using PrestaShopWebservice
's get()
method.
Creating and adding
Creating and adding data takes a bit more work. Indeed, in order to create a new entry or edit an existing one, you need to send a fully formed and complete XML document, whether you use PrestaShopWebservice
or the HTTP methods.
...
Code Block |
---|
// Returns a blank XML document, with all the tags ready to fill http://[email protected]/api/manufacturers?schema=blank // Returns a blank XML document, with all the tags ready to fill and indication of the expected value for each http://[email protected]/api/manufacturers?schema=synopsis |
Deleting
The RESTful-ness of the API goes all the way: in order to delete the product with an ID of 12, you simply have to launch an HTTP DELETE request on the following URL:
Code Block |
---|
http://[email protected]/api/products/12/ |
Available resources
The /api/
URL gives you the root of all the resources, in the form of an XML file.
...