Upgrade Guide

API Platform 3.1/3.2

This is the recommended configuration for API Platform 3.2. We review each of these changes in this document.

api_platform:
    title: Hello API Platform
    version: 1.0.0
    formats:
        jsonld: ['application/ld+json']
    docs_formats:
        jsonld: ['application/ld+json']
        jsonopenapi: ['application/vnd.openapi+json']
        html: ['text/html']
    defaults:
        stateless: true
        cache_headers:
            vary: ['Content-Type', 'Authorization', 'Origin']
        extra_properties:
            standard_put: true
            rfc_7807_compliant_errors: true
    event_listeners_backward_compatibility_layer: false
    keep_legacy_inflector: false

Formats

We noticed that API Platform was enabling json by default because of our OpenAPI support. We introduced the new application/vnd.openapi+json. Therefore if you want json you need to explicitly handle it:

formats: 
    json: ['application/json']

You can also remove documentations you’re not using via the new docs_formats.

A new option error_formats is also used for content negotiation.

Event listeners

For new users we recommend to use

event_listeners_backward_compatibility_layer: false

This allows API Platform to not use http kernel event listeners. It also allows you to force options like read: true or validate: true. This simplifies use cases like validating a delete operation Event listeners will not get removed and are not deprecated, they’ll use our providers and processors in a future version.

Inflector

We’re switching to symfony/string inflector, to keep using doctrine/inflector use:

keep_legacy_inflector: true

We strongly recommend that you use your own inflector anyways with a PathSegmentNameGenerator.

Errors

defaults:
    extra_properties:
        rfc_7807_compliant_errors: true

As this is an extraProperties it’s configurable per resource/operation. This is improving the compatibility of Hydra errors with JSON problem. It also enables new extension points on Errors such as Error provider and Error Resource.

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