Grapic dots

Defining API-Platform Resources & Serialization Groups in YAML

Mike Milano

API Platform is a powerful platform to build REST and GraphQL APIs. Resource configuration can be executed in annotation, YAML, or XML.

The docs follow an approach which demonstrates how to configure via annotation first, then often but not always examples are provided for YAML, and less frequently, XML.

Annotating entities is the most intuitive method at first, however the readability of your entity decreases as the complexity of your API increases. This is the reason I lean toward defining AP resources and serialization in YAML config.

Serialization Groups

Serialization groups are one of the most powerful elements of API Platform. (AP)

AP elegantly uses the Symfony Serializer component to normalize and denormalize resource data.

  • Normalize: Transform values from database into what is delivered by the API
    • Think of this as a read
  • Denormalize: Transform values submitted to the API, into database values
    • Think of this as a write

After creating a group named read for normalization, and a group named write for denormalization, we can apply the groups to each property based on if they should be readable or writable.

Let’s look at the annotated Book entity from the serialization documentation.

  1. <?php
  2. // src/Entity/Book.php
  4. namespace App\Entity;
  6. use ApiPlatform\Core\Annotation\ApiResource;
  7. use Symfony\Component\Serializer\Annotation\Groups;
  9. /**
  10.  * @ApiResource(
  11.  * normalizationContext={"groups"={"read"}},
  12.  * denormalizationContext={"groups"={"write"}}
  13.  * )
  14.  */
  15. class Book
  16. {
  17. /**
  18.   * @Groups({"read", "write"})
  19.   */
  20. private $name;
  22. /**
  23.   * @Groups("write")
  24.   */
  25. private $author;
  27. // ...
  28. }

Let’s take a step back to the point of annotation clutter. I’m just demonstrating serializer groups here, but if we had annotation for operations, access, etc… it would be much more difficult to reason about an entity file. This is why I prefer YAML, for API resource documentation at least.

To migrate the config above to YAML, you will need 2 files:

  1. # config/api_platform/resources.yaml
  2. App\Entity\Book:
  3. attributes:
  4. normalization_context:
  5. groups: ['read']
  6. denormalization_context:
  7. groups: ['write']

The next file is in config/serialization because it just follows the standard serializer component approach. If you haven’t explored serializers before, consider this use case to hit the ground running a little faster.

  1. # config/serialization/Book.yaml
  2. App\Entity\Book:
  3. attributes:
  4. name:
  5. groups: ['read', 'write']
  6. author:
  7. groups: ['write']

Once these are in place, your API should work as expected without any API Platform related annotation in your entity.

8 Reasons Why Standardizing on Drupal is the Right Choice for Enterprise.
Read about it in this free white paper.

Download for Free Now!