Guides

References

    Tutorials

    In depth

    Reference
    A
    Attribute

    ApiPlatform\Metadata\ApiResource

    OptionTypesDescription
    uriTemplatestring
    shortNamestring
    descriptionstring
    typesarray
    string
    operationsarray<int, ApiPlatform\Metadata\HttpOperation>
    array<string, ApiPlatform\Metadata\HttpOperation>
    ApiPlatform\Metadata\Operations    		Operations is a list of HttpOperation
    formatsarray
    string
    inputFormatsarray
    string
    outputFormatsarray
    string
    uriVariablesarray<string, ApiPlatform\Metadata\Link>
    array<string, array<int>>
    array<int, string>
    string
    routePrefixstring
    defaultsarray
    requirementsarray
    optionsarray
    statelessbool
    sunsetstring
    acceptPatchstring
    statusint
    hoststring
    schemesarray
    conditionstring
    controllerstring
    classstring
    urlGenerationStrategyint
    deprecationReasonstring
    cacheHeadersarray
    normalizationContextarray
    denormalizationContextarray
    collectDenormalizationErrorsbool
    hydraContextarray
    openapiContextarray
    openapiApiPlatform\OpenApi\Model\Operation
    bool
    validationContextarray
    filtersarray
    elasticsearchbool
    mercure
    messenger
    input
    output
    orderarray
    fetchPartialbool
    forceEagerbool
    paginationClientEnabledbool
    paginationClientItemsPerPagebool
    paginationClientPartialbool
    paginationViaCursorarray
    paginationEnabledbool
    paginationFetchJoinCollectionbool
    paginationUseOutputWalkersbool
    paginationItemsPerPageint
    paginationMaximumItemsPerPageint
    paginationPartialbool
    paginationTypestring
    securitystring
    securityMessagestring
    securityPostDenormalizestring
    securityPostDenormalizeMessagestring
    securityPostValidationstring
    securityPostValidationMessagestring
    compositeIdentifierbool
    exceptionToStatusarray
    queryParameterValidationEnabledbool
    graphQlOperationsarray
    providerstring
    callable
    processorstring
    callable
    stateOptionsApiPlatform\State\OptionsInterface
    extraPropertiesarray

    Description

    Resource metadata attribute.

    The API Resource attribute declares the behaviors attached to a Resource inside API Platform. This class is immutable, and if you set a value yourself, API Platform will not override the value. The API Resource helps sharing options with operations.

    Read more about how metadata works here.

    Options

    operations

    provider

    string|callable $provider
    string|callable $provider

    processor

    string|callable $processor
    string|callable $processor

    uriTemplate

    string $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
    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
    string $description

    A description for this resource that will show on documentations.

    types

    array|string $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
    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'],
  ]
)]
    #[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
    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(),
 ])]
     #[ApiResource(formats: ['jsonld', 'csv' => ['text/csv']], operations: [
     new Patch(inputFormats: ['json' => ['application/merge-patch+json']]),
     new GetCollection(),
     new Post(),
 ])]

    outputFormats

    array|string $outputFormats
    array|string $outputFormats

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

    uriVariables

    $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()]
  )]
      #[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
    string $routePrefix

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

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

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

    defaults

    array $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
    array $requirements

    The requirements option configures the Symfony's Route requirements.

    options

    array $options
    array $options

    The options option configures the Symfony's Route options.

    stateless

    bool $stateless
    bool $stateless

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

    sunset

    string $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
{
    // ...
}
    <?php
// api/src/Entity/Parchment.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(deprecationReason: 'Create a Book instead', sunset: '01/01/2020')]
class Parchment
{
    // ...
}

    acceptPatch

    string $acceptPatch
    string $acceptPatch

    status

    int $status
    int $status

    host

    string $host
    string $host

    schemes

    array $schemes
    array $schemes

    condition

    string $condition
    string $condition

    controller

    string $controller
    string $controller

    class

    string $class
    string $class

    urlGenerationStrategy

    int $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Api\UrlGeneratorInterface;
 
#[ApiResource(urlGenerationStrategy: UrlGeneratorInterface::ABS_URL)]
class Book
{
    // ...
}

    deprecationReason

    string $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
{
    // ...
}
    <?php
// api/src/Entity/Parchment.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(deprecationReason: 'Create a Book instead')]
class Parchment
{
    // ...
}

    cacheHeaders

    array $cacheHeaders
    array $cacheHeaders

    normalizationContext

    array $normalizationContext
    array $normalizationContext

    denormalizationContext

    array $denormalizationContext
    array $denormalizationContext

    collectDenormalizationErrors

    bool $collectDenormalizationErrors
    bool $collectDenormalizationErrors

    hydraContext

    array $hydraContext
    array $hydraContext

    openapiContext

    array $openapiContext
    array $openapiContext

    openapi

    validationContext

    array $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']])]
    #[ApiResource(validationContext: ['groups' => ['a', 'b']])]

    For more examples, read our guide on validation.

    filters

    array $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(filters: ['app.filters.book.search'])]
class Book
{
    // ...
}

    elasticsearch

    bool $elasticsearch
    bool $elasticsearch

    mercure

    $mercure
    $mercure

    messenger

    string|bool $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(messenger: true)]
class Book
{
    // ...
}

    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
    $input

    output

    $output
    $output

    order

    array $order
    array $order

    fetchPartial

    bool $fetchPartial
    bool $fetchPartial

    forceEager

    bool $forceEager
    bool $forceEager

    paginationClientEnabled

    bool $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationClientEnabled: true)]
class Book
{
    // ...
}

    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
    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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationClientItemsPerPage: true)]
class Book
{
    // ...
}

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

    • GET /books?itemsPerPage=50

    paginationClientPartial

    bool $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationClientPartial: true)]
class Book
{
    // ...
}

    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
    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
{
    // ...
}
    <?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
{
    // ...
}

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

    paginationEnabled

    bool $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationEnabled: true)]
class Book
{
    // ...
}

    paginationFetchJoinCollection

    bool $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationFetchJoinCollection: false)]
class Book
{
    // ...
}

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

    paginationUseOutputWalkers

    bool $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationUseOutputWalkers: false)]
class Book
{
    // ...
}

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

    paginationItemsPerPage

    int $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationItemsPerPage: 30)]
class Book
{
    // ...
}

    paginationMaximumItemsPerPage

    int $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationMaximumItemsPerPage: 50)]
class Book
{
    // ...
}

    paginationPartial

    bool $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationPartial: true)]
class Book
{
    // ...
}

    paginationType

    string $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
{
    // ...
}
    <?php
// api/src/Entity/Book.php
use ApiPlatform\Metadata\ApiResource;
 
#[ApiResource(paginationType: 'page')]
class Book
{
    // ...
}

    security

    string $security
    string $security

    securityMessage

    string $securityMessage
    string $securityMessage

    securityPostDenormalize

    string $securityPostDenormalize
    string $securityPostDenormalize

    securityPostDenormalizeMessage

    string $securityPostDenormalizeMessage
    string $securityPostDenormalizeMessage

    securityPostValidation

    string $securityPostValidation
    string $securityPostValidation

    securityPostValidationMessage

    string $securityPostValidationMessage
    string $securityPostValidationMessage

    compositeIdentifier

    bool $compositeIdentifier
    bool $compositeIdentifier

    exceptionToStatus

    array $exceptionToStatus
    array $exceptionToStatus

    queryParameterValidationEnabled

    bool $queryParameterValidationEnabled
    bool $queryParameterValidationEnabled

    graphQlOperations

    array $graphQlOperations
    array $graphQlOperations

    stateOptions

    ApiPlatform\State\OptionsInterface $stateOptions
    ApiPlatform\State\OptionsInterface $stateOptions

    extraProperties

    array $extraProperties
    array $extraProperties

    Copyright © 2023 Kévin Dunglas

    Sponsored by Les-Tilleuls.coop

    Resources

    LogosWallpapersColouring webby
    HelpScreencastsStack overflowSlackCode of conductReport issues
    CommunityEventsAPI Platform ConferenceContributorsTwitterGithubContribute

    Code licensed under MIT, documentation under CC by 3.0

    Enterprise subscriptionSecurity PolicyTrademark Policy