Legacy Webservice API
Relevant source files
The following files were used as context for generating this wiki page:
The Legacy Webservice API provides a programmatic interface for external applications to interact with PrestaShop resources. It supports standard CRUD (Create, Read, Update, Delete) operations using XML as the primary data exchange format. The system allows for granular permission control per resource and HTTP method.
Sources: tests/UI/campaigns/functional/WS/05_categoriesCRUD.ts, tests/UI/campaigns/functional/WS/03_productsCRUD.ts
Architecture and Authentication
The API operates via HTTP requests directed at specific resource endpoints. Authentication requires a Webservice Key, which you must enable in the Back Office under Advanced Parameters. The API uses Basic Authentication, where the key is provided as the username and the password remains blank.
Authentication Flow
This diagram shows how a client authenticates to access a restricted resource like Products.
Supported HTTP Methods
The API follows RESTful principles for managing resources. Each resource supports a set of methods that correlate to specific database actions.
| Method | Action | Description |
|---|---|---|
| GET | Read | Retrieves a list of resources or a specific resource by ID. |
| POST | Create | Adds a new resource entry to the system. |
| PUT | Update | Modifies an existing resource identified by ID. |
| DELETE | Delete | Removes a resource from the system. |
Sources: tests/UI/campaigns/functional/WS/05_categoriesCRUD.ts:25-30, tests/UI/campaigns/functional/WS/04_storesCRUD.ts:48-52
Resource Schemas
The API provides two special schema types to help you understand resource structures before performing operations.
Blank Schema
The ?schema=blank parameter returns an empty XML structure for the resource. You use this as a template for creating new records via POST. All nodes and attributes in this response have empty values.
Sources: tests/UI/campaigns/functional/WS/05_categoriesCRUD.ts:109-152
Synopsis Schema
The ?schema=synopsis parameter returns a structural overview of the resource. It includes metadata attributes for each node, such as:
required: Indicates if the field is mandatory.format: Defines the data type or regex validation pattern.readOnly: Specifies fields that cannot be modified by the user.
Sources: tests/UI/campaigns/functional/WS/05_categoriesCRUD.ts:154-194, tests/UI/campaigns/functional/WS/04_storesCRUD.ts:176-222
Core Resources and Data Models
The API exposes various entities. Each resource typically includes localized fields for multi-language support and standard metadata like creation dates.
Resource Examples
| Resource | Key Fields | Localized Fields |
|---|---|---|
| Products | price, active, id_manufacturer, reference | name, description, link_rewrite |
| Categories | id_parent, active, is_root_category | name, description, meta_title |
| Stores | latitude, longitude, phone, email, active | name, address1, hours, note |
| Countries | iso_code, call_prefix, id_zone, active | name |
Sources: tests/UI/campaigns/functional/WS/03_productsCRUD.ts:315-600, tests/UI/campaigns/functional/WS/04_storesCRUD.ts:400-550, tests/UI/campaigns/functional/WS/01_countriesCRUD.ts:310-400
Data Relationship Flow
This diagram illustrates how resources like Products interact with localized data and category structures.
Response Structure
Every successful response is wrapped in a <prestashop> root node.
- List Requests: Return a container node (e.g.,
<products>) containing individual resource nodes withidandxlink:hrefattributes. - Specific Resource Requests: Return the full resource node (e.g.,
<product>) with all permitted fields.
Status Codes
- 200 OK: Successful GET, PUT, or DELETE operation.
- 201 Created: Successful POST operation.
- 404 Not Found: The requested resource ID does not exist.
- 401/403: Authentication or permission failure.
Sources: tests/UI/campaigns/functional/WS/03_productsCRUD.ts:210-250, tests/UI/campaigns/functional/WS/04_storesCRUD.ts:300-330
Implementation Notes for Modern API Routes
While the legacy system uses XML, PrestaShop also supports a newer API structure for specific modules like Warehouse. These modern routes:
- Must be declared in
routing/api/YAML files. - Require controllers to extend
ApiControllerand returnJsonResponse. - Support a standardized JSON structure including
info(for pagination) anddata(for the payload).
Sources: src/PrestaShopBundle/Controller/Api/Readme.md:1-80
The Legacy Webservice API remains the primary tool for comprehensive shop management, supporting complex entities like products and categories through a robust XML-based request-response model.
Sources: tests/UI/campaigns/functional/WS/03_productsCRUD.ts, tests/UI/campaigns/functional/WS/05_categoriesCRUD.ts