Api Platform conference
Register now
API Platform Conference
September 19-20, 2024 | Lille & online

The international conference on the API Platform Framework

API Platform Conference 2024: meet the best PHP, JavaScript and API experts

Learn more about the event, register for the conference, and get ready for two days of inspiration, ideas, and knowledge-sharing with our incredible lineup of renowned specialists and advocates.

Register now

Overriding Default Order

API Platform provides an easy way to override the default order of items in your collection.

By default, items in the collection are ordered in ascending (ASC) order by their resource identifier(s). If you want to customize this order, you must add an order attribute on your ApiResource annotation:

<?php
// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;

#[ApiResource(order: ['foo' => 'ASC'])]
class Book
{
    // ...

    /**
     * ...
     */
    public $foo;
    
    // ...
}
# api/config/api_platform/resources/Book.yaml
App\Entity\Book:
    order:
        foo: ASC

This order attribute is used as an array: the key defines the order field, the values defines the direction. If you only specify the key, ASC direction will be used as default. For example, to order by foo & bar:

<?php
// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;

#[ApiResource(order: ['foo', 'bar'])]
class Book
{
    // ...

    /**
     * ...
     */
    public $foo;

    /**
     * ...
     */
    public $bar;
    
    // ...
}
# api/config/api_platform/resources/Book.yaml
App\Entity\Book:
    order: ['foo', 'bar']

It’s also possible to configure the default order on an association property:

<?php
// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;

#[ApiResource(order: ['author.username'])]
class Book
{
    // ...

    /**
     * @var User
     */
    public $author;
    
    // ...
}
# api/config/api_platform/resources/Book.yaml
App\Entity\Book:
    order: ['author.username']

Another possibility is to apply the default order for a specific collection operation, which will override the global default order configuration.

<?php
// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(operations: [
    new GetCollection(),
    new GetCollection(name: 'get_desc_custom', uriTemplate: 'custom_collection_desc_foos', order: ['name' => 'DESC'])],
    new GetCollection(name: 'get_asc_custom', uriTemplate: 'custom_collection_asc_foos', order: ['name' => 'ASC'])]
])]
class Book
{
    // ...

    /**
     * @var string
     */
    public $name;
    
    // ...
}
# api/config/api_platform/resources/Book.yaml
App\Entity\Book:
    ApiPlatform\Metadata\GetCollection: ~
    get_desc_custom:
        class: ApiPlatform\Metadata\GetCollection
        uriTemplate: custom_collection_desc_foos
        order:
            name: DESC
    get_asc_custom:
        class: ApiPlatform\Metadata\GetCollection
        uriTemplate: custom_collection_asc_foos
        order:
            name: ASC

You can also help us improve the documentation of this page.

Made with love by

Les-Tilleuls.coop can help you design and develop your APIs and web projects, and train your teams in API Platform, Symfony, Next.js, Kubernetes and a wide range of other technologies.

Learn more

Copyright © 2023 Kévin Dunglas

Sponsored by Les-Tilleuls.coop