PrestaShop API

How to create a new route

1/ Declare your route

You must declare your route in one of the files in: src/PrestaShopBundle/Resources/config/routing/api/path/to/file.yml.

If the file corresponding to your context does not exist, you can create it by taking care of declaring your new route file in: src/PrestaShopBundle/Resources/config/routing/api.yml

Example, you want a route showing you the list of the warehouses available: in src/PrestaShopBundle/Resources/config/routing/api/warehouse.yml, add (if it does not exist)

_api_warehouse:
    resource: "api/warehouse.yml"

Then, create a file named src/PrestaShopBundle/Resources/config/routing/api/warehouse.yml and add your route:

api_warehouse_list_warehouses:
    path: /warehouses
    methods: [GET]
    defaults:
        _controller: PrestaShopBundle\Controller\Api\WarehouseController::listWarehousesAction

2/ Create your controller

1. API controllers are in the folder: src/PrestaShopBundle/Controller/Api/xxxController.php. In our example, create src/PrestaShopBundle/Controller/Api/WarehouseController.php if it does not exist.

2. Register your controller in the services.yml located in: src/PrestaShopBundle/Resources/config/services.yml like other API controllers (search # Api - Controllers). You need to register with the same id you put on your routing_xxx.yml (here, prestashop.core.api.warehouse.controller).

3. Extend your controller with ApiController, then you should be able to use the Symfony container in your controller.

4. All your functions must return a JsonResponse.

5. Please, be simple, small controllers (using Services if you need).

3/ Create Entities, Repositories and Services! (Optional)

Please, do not use Legacy PrestaShop classes, create your own Service related to your context. (Here, Warehouse for example). Like your controllers, register them in the services.yml. Your controller must be really simple, for the same warehouse example, we can imagine something like this:

public function listWarehousesAction()
{
    $warehouses = $this->warehouseRepository->getWarehouse($tree = true);
    return new JsonResponse($warehouses, 200);
}

And put your logic into the Repository. If the logic is more complicated or not related to the entity, use services.

4/ JSON return nomenclature

We have 2 cases:

1. Simple list of data, return something like:

$result = array(
    'data' => array(
        array(
            'id' => 1,
            'name' => 'Example 1',
        ),
        array(
            'id' => 2,
            'name' => 'Example 2',
        )
    )
);

2. A recursive data (for example, a tree), you must have a tree and children keys, return something like:

$result = array(
    'data' => array(
        'tree' => array(
            'children' => array(
                array(
                    'id' => 1,
                    'name' => 'Example 1',
                    'children' => array(
                        array(
                            'id' => 11,
                            'name' => 'Children 1.1',
                        ),
                        array(
                            'id' => 12,
                            'name' => 'Children 1.2',
                        )
                    )
                ),
                array(
                    'id' => 2,
                    'name' => 'Example 2',
                    'children' => array(
                        array(
                            'id' => 21,
                            'name' => 'Children 2.1',
                        ),
                        array(
                            'id' => 22,
                            'name' => 'Children 2.2',
                        )
                    )
                )
            )
        )
    )
);

Moreover, we can send information about request in a array info like that:

$result = array(
    'info' => array(
        'current_url' => 'http://yoururl.com/api/...'
        'next_url' => 'http://yoururl.com/api/...?page_index=3'
        'previous_url' => 'http://yoururl.com/api/...?page_index=1'
        'page_index' => 1,
        'page_size' => 100,
    )
    'data' => array() // with your data like above
);

Be careful, some routes do not have pagination parameters because sometimes it is not relevant.