References ErrorResource
Reference
A
Attribute

ApiPlatform\Metadata\ErrorResource

OptionTypesDescription
`uriTemplate`string
`shortName`string
`description`string
`types`array
string
`operations`
`formats`
`inputFormats`
`outputFormats`
`uriVariables`
`routePrefix`string
`defaults`array
`requirements`array
`options`array
`stateless`bool
`sunset`string
`acceptPatch`string
`status`int
`host`string
`schemes`array
`condition`string
`controller`string
`class`string
`urlGenerationStrategy`int
`deprecationReason`string
`cacheHeaders`array
`normalizationContext`array
`denormalizationContext`array
`collectDenormalizationErrors`bool
`hydraContext`array
`openapiContext`array
`openapi``ApiPlatform\OpenApi\Model\Operation`
bool
`validationContext`array
`filters`array
`elasticsearch`bool
`mercure`
`messenger`
`input`
`output`
`order`array
`fetchPartial`bool
`forceEager`bool
`paginationClientEnabled`bool
`paginationClientItemsPerPage`bool
`paginationClientPartial`bool
`paginationViaCursor`array
`paginationEnabled`bool
`paginationFetchJoinCollection`bool
`paginationUseOutputWalkers`bool
`paginationItemsPerPage`int
`paginationMaximumItemsPerPage`int
`paginationPartial`bool
`paginationType`string
`security`Stringable
string
`securityMessage`string
`securityPostDenormalize`Stringable
string
`securityPostDenormalizeMessage`string
`securityPostValidation`Stringable
string
`securityPostValidationMessage`string
`compositeIdentifier`bool
`exceptionToStatus`array
`queryParameterValidationEnabled`bool
`graphQlOperations`array
`provider`
`processor`
`stateOptions``ApiPlatform\State\OptionsInterface`
`extraProperties`array

Description

Options

operations

uriTemplate

string $uriTemplate

The URI template represents your resource IRI with optional variables. It follows RFC 6570. API Platform generates this URL for you if you leave this empty.

shortName

string $shortName

The short name of your resource is a unique name that identifies your resource. It is used within the documentation and for url generation if the uriTemplate is not filled. By default, this will be the name of your PHP class.

description

string $description

A description for this resource that will show on documentations.

types

array|string $types

The RDF types of this resource. An RDF type is usually a URI referencing how your resource is structured for the outside world. Values can be a string https://schema.org/Book or an array of string ['https://schema.org/Flight', 'https://schema.org/BusTrip'].

formats

array|string $formats

The formats option allows you to customize content negotiation. By default API Platform supports JsonLd, Hal, JsonAPI. For other formats we use the Symfony Serializer.

#[ApiResource(
  formats: [
      'jsonld' => ['application/ld+json'],
      'jsonhal' => ['application/hal+json'],
      'jsonapi' => ['application/vnd.api+json'],
      'json' =>    ['application/json'],
      'xml' =>     ['application/xml', 'text/xml'],
      'yaml' =>    ['application/x-yaml'],
      'csv' =>     ['text/csv'],
      'html' =>    ['text/html'],
      'myformat' =>['application/vnd.myformat'],
  ]
)]

Learn more about custom formats in the dedicated guide.

inputFormats

array|string $inputFormats

The inputFormats option allows you to customize content negotiation for HTTP bodies:.

 #[ApiResource(formats: ['jsonld', 'csv' => ['text/csv']], operations: [
     new Patch(inputFormats: ['json' => ['application/merge-patch+json']]),
     new GetCollection(),
     new Post(),
 ])]

outputFormats

array|string $outputFormats

The outputFormats option allows you to customize content negotiation for HTTP responses.

uriVariables

$uriVariables

The uriVariables configuration allows to configure to what each URI Variable. With simple string expansion, we read the input value and match this to the given Link. Note that this setting is usually used on an operation directly:.

  #[ApiResource(
      uriTemplate: '/companies/{companyId}/employees/{id}',
      uriVariables: [
          'companyId' => new Link(fromClass: Company::class, toProperty: 'company']),
          'id' => new Link(fromClass: Employee::class)
      ],
      operations: [new Get()]
  )]

For more examples, read our guide on subresources.

routePrefix

string $routePrefix

The routePrefix allows you to configure a prefix that will apply to this resource.

  #[ApiResource(
      routePrefix: '/books',
      operations: [new Get(uriTemplate: '/{id}')]
  )]

This resource will be accessible through /books/{id}.

defaults

array $defaults

The defaults option adds up to Symfony’s route defaults. You can override API Platform’s defaults if needed.

requirements

array $requirements

The requirements option configures the Symfony’s Route requirements.

options

array $options

The options option configures the Symfony’s Route options.

stateless

bool $stateless

The stateless option configures the Symfony’s Route stateless option.

sunset

string $sunset

The sunset option indicates when a deprecated operation will be removed.

<?php
// api/src/Entity/Parchment.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(deprecationReason: 'Create a Book instead', sunset: '01/01/2020')]
class Parchment
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Parchment:
        - deprecationReason: 'Create a Book instead'
          sunset: '01/01/2020'
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Parchment" deprecationReason="Create a Book instead" sunset="01/01/2020" />
</resources>

acceptPatch

string $acceptPatch

status

int $status

host

string $host

schemes

array $schemes

condition

string $condition

controller

string $controller

class

string $class

urlGenerationStrategy

int $urlGenerationStrategy

The urlGenerationStrategy option configures the url generation strategy.

See: UrlGeneratorInterface::class

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Api\UrlGeneratorInterface;

#[ApiResource(urlGenerationStrategy: UrlGeneratorInterface::ABS_URL)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
App\Entity\Book:
    urlGenerationStrategy: !php/const ApiPlatform\Api\UrlGeneratorInterface::ABS_URL
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" urlGenerationStrategy="0" />
</resources>

deprecationReason

string $deprecationReason

The deprecationReason option deprecates the current resource with a deprecation message.

<?php
// api/src/Entity/Parchment.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(deprecationReason: 'Create a Book instead')]
class Parchment
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Parchment:
        - deprecationReason: 'Create a Book instead'
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Parchment" deprecationReason="Create a Book instead" />
</resources>

headers

array $headers

cacheHeaders

array $cacheHeaders

normalizationContext

array $normalizationContext

denormalizationContext

array $denormalizationContext

collectDenormalizationErrors

bool $collectDenormalizationErrors

hydraContext

array $hydraContext

openapiContext

array $openapiContext

openapi

validationContext

array $validationContext

The validationContext option configures the context of validation for the current ApiResource. You can, for instance, describe the validation groups that will be used:.

#[ApiResource(validationContext: ['groups' => ['a', 'b']])]

For more examples, read our guide on validation.

filters

array $filters

The filters option configures the filters (declared as services) available on the collection routes for the current resource.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(filters: ['app.filters.book.search'])]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - filters: ['app.filters.book.search']
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->
<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book">
        <filters>
            <filter>app.filters.book.search</filter>
        </filters>
    </resource>
</resources>

elasticsearch

bool $elasticsearch

mercure

$mercure

messenger

string|bool $messenger

The messenger option dispatches the current resource through the Message Bus.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(messenger: true)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - messenger: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" messenger=true />
</resources>

Note: when using messenger=true on a Doctrine entity, the Doctrine Processor is not called. If you want it to be called, you should decorate a built-in state processor and implement your own logic.

Read how to use Messenger with an Input object.

input

$input

output

$output

order

array $order

Override the default order of items in your collection. Note that this is handled by our doctrine filters such as the OrderFilter.

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
{
}
# 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.

fetchPartial

bool $fetchPartial

forceEager

bool $forceEager

paginationClientEnabled

bool $paginationClientEnabled

The paginationClientEnabled option allows (or disallows) the client to enable (or disable) the pagination for the current resource.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationClientEnabled: true)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationClientEnabled: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationClientEnabled=true />
</resources>

The pagination can now be enabled (or disabled) by adding a query parameter named pagination:

  • GET /books?pagination=false: disabled
  • GET /books?pagination=true: enabled

paginationClientItemsPerPage

bool $paginationClientItemsPerPage

The paginationClientItemsPerPage option allows (or disallows) the client to set the number of items per page for the current resource.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationClientItemsPerPage: true)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationClientItemsPerPage: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationClientItemsPerPage=true />
</resources>

The number of items can now be set by adding a query parameter named itemsPerPage:

  • GET /books?itemsPerPage=50

paginationClientPartial

bool $paginationClientPartial

The paginationClientPartial option allows (or disallows) the client to enable (or disable) the partial pagination for the current resource.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationClientPartial: true)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationClientPartial: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationClientPartial=true />
</resources>

The partial pagination can now be enabled (or disabled) by adding a query parameter named partial:

  • GET /books?partial=false: disabled
  • GET /books?partial=true: enabled

paginationViaCursor

array $paginationViaCursor

The paginationViaCursor option configures the cursor-based pagination for the current resource. Select your unique sorted field as well as the direction you’ll like the pagination to go via filters. Note that for now you have to declare a RangeFilter and an OrderFilter on the property used for the cursor-based pagination:.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Doctrine\Odm\Filter\OrderFilter;
use ApiPlatform\Doctrine\Odm\Filter\RangeFilter;

#[ApiResource(paginationPartial: true, paginationViaCursor: [['field' => 'id', 'direction' => 'DESC']])]
#[ApiFilter(RangeFilter::class, properties: ["id"])]
#[ApiFilter(OrderFilter::class, properties: ["id" => "DESC"])]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationPartial: true
          paginationViaCursor:
              - { field: 'id', direction: 'DESC' }
          filters: [ 'app.filters.book.range', 'app.filters.book.order' ]
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationPartial=true>
        <filters>
            <filter>app.filters.book.range</filter>
            <filter>app.filters.book.order</filter>
        </filters>
        <paginationViaCursor>
            <paginationField field="id" direction="DESC" />
        </paginationViaCursor>
    </resource>
</resources>

To know more about cursor-based pagination take a look at this blog post on medium (draft).

paginationEnabled

bool $paginationEnabled

The paginationEnabled option enables (or disables) the pagination for the current resource.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationEnabled: true)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationEnabled: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationEnabled=true />
</resources>

paginationFetchJoinCollection

bool $paginationFetchJoinCollection

The PaginationExtension of API Platform performs some checks on the QueryBuilder to guess, in most common cases, the correct values to use when configuring the Doctrine ORM Paginator: $fetchJoinCollection argument, whether there is a join to a collection-valued association.

When set to true, the Doctrine ORM Paginator will perform an additional query, in order to get the correct number of results. You can configure this using the paginationFetchJoinCollection option:

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationFetchJoinCollection: false)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationFetchJoinCollection: false
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationFetchJoinCollection=false />
</resources>

For more information, please see the Pagination entry in the Doctrine ORM documentation.

paginationUseOutputWalkers

bool $paginationUseOutputWalkers

The PaginationExtension of API Platform performs some checks on the QueryBuilder to guess, in most common cases, the correct values to use when configuring the Doctrine ORM Paginator: $setUseOutputWalkers setter, whether to use output walkers.

When set to true, the Doctrine ORM Paginator will use output walkers, which are compulsory for some types of queries. You can configure this using the paginationUseOutputWalkers option:

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationUseOutputWalkers: false)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationUseOutputWalkers: false
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->
<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationUseOutputWalkers=false />
</resources>

For more information, please see the Pagination entry in the Doctrine ORM documentation.

paginationItemsPerPage

int $paginationItemsPerPage

The paginationItemsPerPage option defines the number of items per page for the current resource.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationItemsPerPage: 30)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationItemsPerPage: 30
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->
<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationItemsPerPage=30 />
</resources>

paginationMaximumItemsPerPage

int $paginationMaximumItemsPerPage

The paginationMaximumItemsPerPage option defines the maximum number of items per page for the current resource.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationMaximumItemsPerPage: 50)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationMaximumItemsPerPage: 50
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->
<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationMaximumItemsPerPage=50 />
</resources>

paginationPartial

bool $paginationPartial

The paginationPartial option enables (or disables) the partial pagination for the current resource.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationPartial: true)]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationPartial: true
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->
<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationPartial=true />
</resources>

paginationType

string $paginationType

The paginationType option defines the type of pagination (page or cursor) to use for the current resource.

<?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(paginationType: 'page')]
class Book
{
    // ...
}
# api/config/api_platform/resources.yaml
resources:
    App\Entity\Book:
        - paginationType: page
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->
<resources
        xmlns="https://api-platform.com/schema/metadata/resources-3.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
        https://api-platform.com/schema/metadata/resources-3.0.xsd">
    <resource class="App\Entity\Book" paginationType="page" />
</resources>

security

Stringable|string $security

securityMessage

string $securityMessage

securityPostDenormalize

Stringable|string $securityPostDenormalize

securityPostDenormalizeMessage

string $securityPostDenormalizeMessage

securityPostValidation

Stringable|string $securityPostValidation

securityPostValidationMessage

string $securityPostValidationMessage

compositeIdentifier

bool $compositeIdentifier

exceptionToStatus

array $exceptionToStatus

queryParameterValidationEnabled

bool $queryParameterValidationEnabled
array $links

graphQlOperations

array $graphQlOperations

stateOptions

parameters

extraProperties

array $extraProperties

provider

$provider

processor

$processor

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