Admin API & API Platform Integration
Relevant source files
The following files were used as context for generating this wiki page:
- src/PrestaShopBundle/Controller/Api/Readme.md
- tests/UI/campaigns/functional/API/02_endpoints/module/08_getModuleTechnicalName.ts
- tests/UI/campaigns/functional/API/02_endpoints/apiClient/03_getApiClientId.ts
- tests/UI/campaigns/functional/WS/05_categoriesCRUD.ts
- tests/UI/campaigns/modules/07_ps_apiresources/01_installation/01_uninstallAndInstallModule.ts
- tests/UI/campaigns/functional/WS/04_storesCRUD.ts
The PrestaShop Admin API provides a structured interface for managing back-office resources programmatically. It integrates with modern API standards, moving away from legacy PrestaShop classes in favor of dedicated Services, Repositories, and Symfony-based Controllers. The system supports OAuth2 authentication for secure access and provides standardized JSON responses for data manipulation and retrieval.
Sources: src/PrestaShopBundle/Controller/Api/Readme.md:1-50, tests/UI/campaigns/functional/API/02_endpoints/apiClient/03_getApiClientId.ts:89-106
Architecture and Routing
The Admin API utilizes Symfony routing to map HTTP request paths to specific controller actions. Developers declare routes in YAML configuration files located within the src/PrestaShopBundle/Resources/config/routing/api/ directory.
Route Declaration
Routes define the endpoint path, supported HTTP methods (e.g., GET, POST, PUT, DELETE), and the target controller action.
This diagram illustrates the flow of a request from the initial HTTP call through the routing configuration to the database.
Sources: src/PrestaShopBundle/Controller/Api/Readme.md:3-32
Controller Implementation
Controllers must extend PrestaShopBundle\Controller\Api\ApiController to access the Symfony container. Every function within these controllers returns a JsonResponse. The architecture encourages small controllers that offload business logic to specialized Services or Repositories.
Sources: src/PrestaShopBundle/Controller/Api/Readme.md:34-58
Authentication and Security
The API uses an OAuth2-based authentication flow. Clients must obtain an access token using their credentials before accessing protected endpoints.
Authentication Flow
- The client requests an access token from the
/access_tokenendpoint using aclient_idandclient_secret. - The server validates the credentials and returns a Bearer token.
- The client includes this token in the
Authorizationheader for subsequent API requests.
This sequence diagram shows the token acquisition process and its use in resource requests.
Sources: tests/UI/campaigns/functional/API/02_endpoints/apiClient/03_getApiClientId.ts:89-106, tests/UI/campaigns/functional/API/02_endpoints/module/08_getModuleTechnicalName.ts:77-84
Authorization Scopes
Access is restricted by scopes. Specific permissions are required for different resources:
module_read: Permission to view module information.module_write: Permission to modify module status.api_client_read: Permission to view API client details.
Sources: tests/UI/campaigns/functional/API/02_endpoints/module/08_getModuleTechnicalName.ts:31, tests/UI/campaigns/functional/API/02_endpoints/module/05_putModuleTechnicalNameStatus.ts:31, tests/UI/campaigns/functional/API/02_endpoints/apiClient/03_getApiClientId.ts:31
Data Formats and Naming
The API standardizes its output to ensure consistency across different resources.
JSON Response Structure
The API returns data in a wrapper containing data and optionally info keys.
| Key | Type | Description |
|---|---|---|
data | Array/Object | The primary resource data (e.g., a list or a tree). |
info | Array | Metadata including current_url, next_url, and pagination details like page_index and page_size. |
tree | Object | Used for recursive data; contains a children key. |
Sources: src/PrestaShopBundle/Controller/Api/Readme.md:65-117
Resource Schemas
When using XML-based webservices (Legacy transition), the API provides schemas to describe resource structures:
- Blank Schema: Returns an empty XML structure of the resource for creation templates.
- Synopsis Schema: Describes the format, required fields, and read-only attributes of each node.
Sources: tests/UI/campaigns/functional/WS/05_categoriesCRUD.ts:98-150, tests/UI/campaigns/functional/WS/04_storesCRUD.ts:167-219
Resource Management (CRUD)
The system supports full Create, Read, Update, and Delete operations for entities like Categories, Stores, and API Clients.
Module Management Endpoints
Modules are managed via specific technical name endpoints.
| Endpoint | Method | Action |
|---|---|---|
/modules/{technicalName} | GET | Retrieves module ID, version, and installation status. |
/modules/{technicalName}/status | PUT | Enables or disables a module using the enabled boolean. |
Sources: tests/UI/campaigns/functional/API/02_endpoints/module/08_getModuleTechnicalName.ts:90-100, tests/UI/campaigns/functional/API/02_endpoints/module/05_putModuleTechnicalNameStatus.ts:79-85
Implementation Example: Categories
CRUD operations for categories follow standard REST patterns but may involve XML payloads in specific webservice contexts.
API Client Integration
Admin API functionality is often extended or provided by modules such as ps_apiresources. The installation of these modules registers new API scopes and resources in the Back Office.
- Installation: Registering the module adds core and module-specific scopes to the API Client creation interface.
- Uninstallation: Removing the module cleans up these records and removes associated scopes.
Sources: tests/UI/campaigns/modules/07_ps_apiresources/01_installation/01_uninstallAndInstallModule.ts:1-200
Summary
The Admin API integration provides a robust framework for back-office automation. By utilizing Symfony controllers and services, it offers a scalable way to expose PrestaShop resources. The combination of OAuth2 security, standardized JSON structures, and clear routing protocols ensures that developers can build reliable integrations with the PrestaShop ecosystem.