Serialization Groups: Choosing Fields

With a Subscription, click any sentence in the script to jump to that part of the video!

Right now, whether or not a field in our class is readable or writable in the API is entirely determined by whether or not that property is readable or writable in our class (basically, whether or not it has a getter or setter method). But what if you need a getter or setter... but don't want that field exposed in the API? For that, we have two options.

A DTO Class?

Option número uno: create a DTO class for the API resource. This is something we'll save for another day... in a future tutorial. But in a nutshell, it's where you create a dedicated class for your DragonTreasure API... and then move the ApiResource attribute onto that. The key thing is that you'll design the new class to look exactly like your API... because modeling your API will be its only job. It takes a little more work to set things up, but the advantage is that you then have a dedicated class for your API. Done!

Hello Serialization Groups

The second solution, and the one we're going to use, is serialization groups. Check it out. Over on the ApiResource attribute, add a new option called normalizationContext. If you recall, "normalization" is the process of going from an object to an array, like when you're making a GET request to read a treasure. The normalizationContext is basically options that are passed to the serializer during that process. And the one option that's most important is groups. Set that to one group called treasure:read:

            
            142 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 16
                            
            #[ApiResource(
        
                                                    ... lines 18 - 26
                            
                normalizationContext: [
        
                    'groups' => ['treasure:read'],
        
                ]
        
            )]
        
            class DragonTreasure
        
            {
        
                                                    ... lines 33 - 140
                            
            }

We'll talk about what this does in a minute. But you can see the pattern I'm using for the group: the name of the class (it could be dragon_treasure if we wanted) then :read... because normalization means that we're reading this class. You can name these groups however you want: this is my standard.

So... what does that do? Let's find out! Refresh the documentation... and, to make life easier, go to the URL: /api/dragon_treasures.jsonld. Whoops! It's just treasures.jsonld now. There we go. And... absolutely nothing is returned! Ok, we have the hydra fields, but this hydra:member contains the array of treasures. It is returning one treasure... but other than @id and @type... there are no actual fields!

How Serialization Groups Work

Here's the deal. As soon as we add a normalizationContext with a group, when our object is normalized, the serializer will only include properties that have this group on it. And since we haven't added any groups to our properties, it returns nothing.

How do we add groups? With another attribute! Above the $name property, say #[Groups], hit "tab" to add its use statement and then treasure:read. Repeat this above the $description field... because we want that to be readable... and then the $value field... and finally $coolFactor:

            
            147 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 14
                            
            use Symfony\Component\Serializer\Annotation\Groups;
        
                                                    ... lines 16 - 31
                            
            class DragonTreasure
        
            {
        
                                                    ... lines 34 - 39
                            
                #[Groups(['treasure:read'])]
        
                private ?string $name = null;
        
                                                    ... lines 42 - 43
                            
                #[Groups(['treasure:read'])]
        
                private ?string $description = null;
        
                                                    ... lines 46 - 50
                            
                #[Groups(['treasure:read'])]
        
                private ?int $value = null;
        
                                                    ... lines 53 - 54
                            
                #[Groups(['treasure:read'])]
        
                private ?int $coolFactor = null;
        
                                                    ... lines 57 - 145
                            
            }

Good start. Move over and refresh the endpoint. Now... got it! We see name, description, value, and coolFactor.

DenormalizationContext: Controlling Writable Groups

We now have control over which fields are readable... and we can do the same thing to choose which fields should be writeable in the API. That's called "de-normalization", and I bet you can guess what we're going to do. Copy normalizationContext, paste, change it to denormalizationContext... and use treasure:write:

            
            150 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 17
                            
            #[ApiResource(
        
                                                    ... lines 19 - 30
                            
                denormalizationContext: [
        
                    'groups' => ['treasure:write'],
        
                ]
        
            )]
        
            class DragonTreasure
        
            {
        
                                                    ... lines 37 - 148
                            
            }

Now head down to the $name property and add treasure:write. I'm going to skip $description (remember that we actually deleted our setDescription() method earlier on purpose)... but add this to $value... and $coolFactor:

            
            150 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 34
                            
            class DragonTreasure
        
            {
        
                                                    ... lines 37 - 42
                            
                #[Groups(['treasure:read', 'treasure:write'])]
        
                private ?string $name = null;
        
                                                    ... lines 45 - 53
                            
                #[Groups(['treasure:read', 'treasure:write'])]
        
                private ?int $value = null;
        
                                                    ... lines 56 - 57
                            
                #[Groups(['treasure:read', 'treasure:write'])]
        
                private ?int $coolFactor = null;
        
                                                    ... lines 60 - 148
                            
            }

Oh, it's mad at me! As soon as we pass multiple groups, we need to make this an array. Add some [] around those three properties. Much happier.

To check if this is A-OK, refresh the documentation... open up the PUT endpoint, and... sweet! We see name, value, and coolFactor, which are currently the only fields that are writable in our API.

Adding Groups To Methods

We are missing a few things, though. Earlier, we made a getPlunderedAtAgo() method...

            
            150 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 34
                            
            class DragonTreasure
        
            {
        
                                                    ... lines 37 - 132
                            
                public function getPlunderedAtAgo(): string
        
                {
        
                    return Carbon::instance($this->plunderedAt)->diffForHumans();
        
                }
        
                                                    ... lines 137 - 148
                            
            }

and we want this to be included when we read our resource. Right now, if we we check the endpoint, it's not there.

To fix this, we can also add groups above methods. Say #[Groups(['treasure:read'])]:

            
            151 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 34
                            
            class DragonTreasure
        
            {
        
                                                    ... lines 37 - 132
                            
                #[Groups(['treasure:read'])]
        
                public function getPlunderedAtAgo(): string
        
                {
        
                    return Carbon::instance($this->plunderedAt)->diffForHumans();
        
                }
        
                                                    ... lines 138 - 149
                            
            }

And when we go check... voilà, it pops up.

Let's also find the setTextDescription() method... and do the same thing: #[Groups([treasure:write])]:

            
            152 lines
            
            src/Entity/DragonTreasure.php
        
                                                    ... lines 1 - 34
                            
            class DragonTreasure
        
            {
        
                                                    ... lines 37 - 93
                            
                #[Groups(['treasure:write'])]
        
                public function setTextDescription(string $description): self
        
                {
        
                                                    ... lines 97 - 99
                            
                }
        
                                                    ... lines 101 - 150
                            
            }

Awesome! If we head back to the documentation, the field is not currently there... but when we refresh... and check out the PUT endpoint again... textDescription is back!

Re-Adding Methods

Hey, now we can re-add any of the getter or setter methods we removed earlier! Like, maybe I do need a setDescription() method in my code for something. Copy setName() to be lazy, paste and change "name" to "description" in a few places.

Got it! And even though we have that setter back, when we look at the PUT endpoint, description doesn't show up. We have complete control over our fields thanks to the denormalization groups. Do the same thing for setPlunderedAt()... because sometimes it's handy - in data fixtures especially - to be able to set this manually.

And... done!

Adding Field Defaults

So we know that fetching a resource works. Now let's see if we can create a new resource. Click on the POST endpoint, hit "Try it out", and... let's fill in some info about our new treasure, which is, of course, a Giant jar of pickles. This is very valuable and has a coolFactor of 10. I'll also add a description... though this jar of pickles speaks for itself.

When we try this... oh, dear... we get a 500 error:

An exception occurred while executing a query: Not null violation, null value in column isPublished.

We slimmed our API down to only the fields that we want writeable... but there's still one property that must be set in the database. Scroll up and find isPublished. Yup, it currently defaults to null. Change that to = false... and now the property will never be null.

If we try it... the Giant jar of pickles is pickled into the database! It works!

Next: let's explore a few more cool serialization tricks to give us even more control.

Leave a comment!

Roberto | posted 1 month ago

if it helps anybody, the moment you modify the metadata and add attributes, etc, you need to clear the cache unless you run the profiler debug toolbar which does that for you. I was stuck wondering why it didn't worked and that was the reason, then after installing the debugger everything worked fine just by reloading.

1 Reply

Victor | SFCASTS | Roberto | posted 1 month ago

Hey Reborto,

Thank you for this tip! Yeah, it's always a good idea to clear the cache first in any weird case, i.e. when things should work but somehow work not like you expect.

Cheers!

triemli | posted 1 month ago

Hi guys, what the difference between normalization or denormalization contexts placed in ApiResource scope and explicitly for operations get/post/patch/...?

sadikoff | SFCASTS | triemli | posted 29 days ago | edited

Hi @triemli

it will configure serializer behavior for serialize and deserialize operations, you will use groups to select what values you will need to pass from Entity to JSON and vice versa.

Cheers!

1 Reply

Aurelien-A | posted 3 months ago

Hi Ryan,

I watched the API Platform 2 course. I plan to watch this one but for now I did not find the time to do it. I still searched if there was the same course "Automatic Serialization Groups" that was in API Platform 2 course in API Platform 3 course. I could not find it, and it seems that the old version does not work anymore. Do you have any idea about how to do something similar ?

Thank you for your excellent work !

weaverryan | SFCASTS | Aurelien-A | posted 3 months ago

Hey @Aurelien-A!

It's funny you ask about that - it was maybe the ONE thing I didn't include in the API Platform 3 tutorial and at least 2 people have asked about it :P. Here is the other conversation - https://symfonycasts.com/screencast/api-platform/install#comment-29468 - it looks like the feature should be implemented the same way... it's just that some class names changed.

Let me know if you try it and hit any hiccups.

Cheers!

1 Reply

Aurelien-A | weaverryan | posted 3 months ago | HIGHLIGHTED

Hello Ryan, you were right. With a little reworking of the code in your original course, I believe I've managed to reproduce the same operation. I'm leaving the code in question available here, perhaps it could be useful to someone.

Thanks for your help and congratulations for your work on Symfony :)

1 Reply

weaverryan | SFCASTS | Aurelien-A | posted 3 months ago

Ah, thank you for posing that! ❤️❤️❤️ Nice work!

Pierre-A | posted 4 months ago | edited

Just to signal a little fault : ~~DenormlizationContext~~ should be DenormalizationContext in the title "DenormlizationContext: Controlling Writable Groups" ! (i see another but cannot find it after reading the course twice!) But very good job, many thanks !

weaverryan | SFCASTS | Pierre-A | posted 4 months ago

Ah, thank you Pierre! Fixed up now :) https://github.com/SymfonyCasts/api-platform3/commit/d542951c3fb0f33f31eecf9a642edf5da1a02386

Mepcuk | posted 5 months ago

Hi support Team,

maybe you can share few examples with DTO ?

Thanks in advance

weaverryan | SFCASTS | Mepcuk | posted 5 months ago

Hey @Mepcuk!

That's coming! Not until episode 3, but definitely it's coming. It was better to wait until ep3 than try to smash it in earlier - it deserves some space :).

Cheers!

Auro | posted 5 months ago

Hi Ryan,

In this chapter you are talking about the DTO solution, are you going to do a course to explain how it works in Api Platform v3?

I've always used them in v2, to separate the Entities from the Api. But in v3 I encounter a problem I don't know how to solve.

The @id field in DTO looks like "@id": "/.well-known/genid/01e546d3f38c0b5d3b8a", and I don't find anyway to get the IRI instead. Do you know if it's possible?

Thank you in advance

weaverryan | SFCASTS | Auro | posted 5 months ago

Hey @Auro!

In this chapter you are talking about the DTO solution, are you going to do a course to explain how it works in Api Platform v3?

Yes! But not until episode 3 so we can give them proper attention.

The @id field in DTO looks like "@id": "/.well-known/genid/01e546d3f38c0b5d3b8a", and I don't find anyway to get the IRI instead. Do you know if it's possible?

Hmm. This is new to me. It's generating something called a "skolem", which I know almost nothing about. And so, I'm giving advice... without really understanding ;). Looking at the code, which is deep and complex, you could try:

A) Setting force_resource_class: true as under normalizationContext of your ApiResource.
B) There is a new, undocumented feature in API Platform 3.1 that allows you to, sort of, "tie" your DTO to your entity a bit closer. Looking at the code, this seems related - but there are a lot of layers to it, and I'm honestly not sure what it does or doesn't do. But I believe, above your ApiResource in your DTO, you would add <br />stateOptions: new DoctrineORMOptions(entityClass: MyClass::class)<br />

Part of the tricky thing here is that DTO can mean at least 2 different things: a class that actually has the ApiResource attribute on it and IS the resource, or you have that attribute on an entity, then use the input or output config.

Cheers!

Auro | weaverryan | posted 5 months ago | edited

Hi @weaverryan,

Thank you for your answer.

I've tried the two options, and this is my feedback:

A. This solution works perfectly if you use id as default identifier. Sadly is not my case, I use uuid, and I think there is a bug when using uuid.

in the IriConverter class, method generateSymfonyRoute, it calls the following:

$identifiers = $this->identifiersExtractor->getIdentifiersFromItem($resource, $identifiersExtractorOperation, $context);

and in the IdentifiersExtractor class the first line of the getIdentifiersFromItem method

if (!$this->isResourceClass($this->getObjectClass($item))) { return ['id' => $this->propertyAccessor->getValue($item, 'id')]; }

If I use id instead of uuid o replace this line by uuid in both case it works and generate correctly the @id.

Instead of hardcoding the id, i think that it should dynamically use the identifier property

B. Digging into the code, there is a stateOptions but it looks to only works with elasticsearchOptions for the moment.

I have an ultimate question about DTOs, what would be the equivalent of the DataTransformerInitializerInterface?

I'm trying to initialize/hydrate the DTO when working with PUT/PATCH methods, but i don't find any way to have the object initialized before the validation step.

weaverryan | SFCASTS | Auro | posted 4 months ago

Hi @Auro!

Thanks for the update - sorry it's proving so tricky!

Instead of hardcoding the id, i think that it should dynamically use the identifier property

I don't know this code well. But I agree that it seems odd that it is looking specifically for an id property

I have an ultimate question about DTOs, what would be the equivalent of the DataTransformerInitializerInterface?

In short, I don't know yet... because I haven't dug into this - that will be soon for episode 3. They do talk about this briefly in the upgrade doc - https://api-platform.com/docs/core/upgrade-guide/#datatransformers-and-dto-support - you're supposed to use state providers to load the DTO data - https://api-platform.com/docs/core/dto/#implementing-a-write-operation-with-an-input-different-from-the-resource - however, I'm not sure this works yet with relation to validation.

Sorry I can't be more helpful! If you find anything out, I'd love to know :)

Auro | weaverryan | posted 4 months ago | edited

Thank you for your help @weaverryan ,

For the first point i've open an issue

https://github.com/api-platform/api-platform/issues/2411

For the second one, I will wait for the episode 3. I'm already using state providers and it works fine for POST methods. The problem is how to bypass validate and hydrate the DTO before the state provider code is executed.

Auro | Auro | posted 4 months ago | HIGHLIGHTED

Just to give some feeback, i've found a solution that works, but not really sure if it's a hack or the correct way to go.

https://github.com/api-platform/core/issues/5451

api_platform:
    mapping:
        paths: ['%kernel.project_dir%/config/api_platform', '%kernel.project_dir%/src/Dto']

resources:
    App\DomainBundle\Entity\AdminUser:
        normalizationContext:
            groups: [ 'admin-user:read' ]
        denormalizationContext:
            groups: [ 'admin-user:write' ]
        operations:
            ApiPlatform\Metadata\GetCollection:
                output: App\Dto\Output\AdminUserOutput
                provider: App\State\AdminUserCollectionProvider
                filters:
                    - api_platform.filter.admin_user.order
                    - api_platform.filter.admin_user.search
            ApiPlatform\Metadata\Get:
                output: App\Dto\Output\AdminUserOutput
                provider: App\State\AdminUserItemProvider
            ApiPlatform\Metadata\Post:
                processor: App\State\UserProcessor
                validationContext:
                    groups: [ 'Default', 'password' ]
            ApiPlatform\Metadata\Patch:
                processor: App\State\UserProcessor
            ApiPlatform\Metadata\Put:
                processor: App\State\UserProcessor
            ApiPlatform\Metadata\Delete: ~

properties:
    App\DomainBundle\Entity\AdminUser:
        id:
            identifier: false

        uuid:
            identifier: true

<?php

namespace App\Dto\Output;

use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\Get;
use App\DomainBundle\Entity\AdminUser;
use Ramsey\Uuid\UuidInterface;
use Symfony\Component\Serializer\Annotation\Groups;

#[Get(shortName: 'AdminUser')]
final class AdminUserOutput
{
    #[ApiProperty(identifier: true)]
    public UuidInterface $uuid;

    #[ApiProperty(identifier: false)]
    #[Groups('admin-user:read')]
    public int $id;

    #[Groups('admin-user:read')]
    public string $email;

    public function __construct(AdminUser $admin)
    {
        $this->id = $admin->getId();
        $this->uuid = $admin->getUuid();
        $this->email = $admin->getEmail();
    }
}

1 Reply

weaverryan | SFCASTS | Auro | posted 4 months ago

Awesome - thank you for sharing this. I'll have to dig more deeply into it when I look at DTO's. I'm totally unfamiliar with having an operation - like Get() right on the class vs inside of ApiResource 🤔

Symfony 6.2 API Platform 3.0

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=8.1",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "api-platform/core": "^3.0", // v3.0.8
        "doctrine/annotations": "^1.0", // 1.14.2
        "doctrine/doctrine-bundle": "^2.8", // 2.8.0
        "doctrine/doctrine-migrations-bundle": "^3.2", // 3.2.2
        "doctrine/orm": "^2.14", // 2.14.0
        "nelmio/cors-bundle": "^2.2", // 2.2.0
        "nesbot/carbon": "^2.64", // 2.64.1
        "phpdocumentor/reflection-docblock": "^5.3", // 5.3.0
        "phpstan/phpdoc-parser": "^1.15", // 1.15.3
        "symfony/asset": "6.2.*", // v6.2.0
        "symfony/console": "6.2.*", // v6.2.3
        "symfony/dotenv": "6.2.*", // v6.2.0
        "symfony/expression-language": "6.2.*", // v6.2.2
        "symfony/flex": "^2", // v2.2.4
        "symfony/framework-bundle": "6.2.*", // v6.2.3
        "symfony/property-access": "6.2.*", // v6.2.3
        "symfony/property-info": "6.2.*", // v6.2.3
        "symfony/runtime": "6.2.*", // v6.2.0
        "symfony/security-bundle": "6.2.*", // v6.2.3
        "symfony/serializer": "6.2.*", // v6.2.3
        "symfony/twig-bundle": "6.2.*", // v6.2.3
        "symfony/ux-react": "^2.6", // v2.6.1
        "symfony/validator": "6.2.*", // v6.2.3
        "symfony/webpack-encore-bundle": "^1.16", // v1.16.0
        "symfony/yaml": "6.2.*" // v6.2.2
    },
    "require-dev": {
        "doctrine/doctrine-fixtures-bundle": "^3.4", // 3.4.2
        "symfony/debug-bundle": "6.2.*", // v6.2.1
        "symfony/maker-bundle": "^1.48", // v1.48.0
        "symfony/monolog-bundle": "^3.0", // v3.8.0
        "symfony/stopwatch": "6.2.*", // v6.2.0
        "symfony/web-profiler-bundle": "6.2.*", // v6.2.4
        "zenstruck/foundry": "^1.26" // v1.26.0
    }
}

Edit on GitHub

TRACK

APIs >

COURSE

API Platform 3 Part 1: Mythically Good RESTful APIs

Serialization Groups: Choosing Fields

Keep on Learning!

A DTO Class?

Hello Serialization Groups

How Serialization Groups Work

DenormalizationContext: Controlling Writable Groups

Adding Groups To Methods

Re-Adding Methods

Adding Field Defaults

Leave a comment!

What PHP libraries does this tutorial use?

	... lines 1 - 16
	#[ApiResource(
	... lines 18 - 26
	normalizationContext: [
	'groups' => ['treasure:read'],
	]
	)]
	class DragonTreasure
	{
	... lines 33 - 140
	}

	... lines 1 - 14
	use Symfony\Component\Serializer\Annotation\Groups;
	... lines 16 - 31
	class DragonTreasure
	{
	... lines 34 - 39
	#[Groups(['treasure:read'])]
	private ?string $name = null;
	... lines 42 - 43
	#[Groups(['treasure:read'])]
	private ?string $description = null;
	... lines 46 - 50
	#[Groups(['treasure:read'])]
	private ?int $value = null;
	... lines 53 - 54
	#[Groups(['treasure:read'])]
	private ?int $coolFactor = null;
	... lines 57 - 145
	}

	... lines 1 - 17
	#[ApiResource(
	... lines 19 - 30
	denormalizationContext: [
	'groups' => ['treasure:write'],
	]
	)]
	class DragonTreasure
	{
	... lines 37 - 148
	}

	... lines 1 - 34
	class DragonTreasure
	{
	... lines 37 - 42
	#[Groups(['treasure:read', 'treasure:write'])]
	private ?string $name = null;
	... lines 45 - 53
	#[Groups(['treasure:read', 'treasure:write'])]
	private ?int $value = null;
	... lines 56 - 57
	#[Groups(['treasure:read', 'treasure:write'])]
	private ?int $coolFactor = null;
	... lines 60 - 148
	}

	... lines 1 - 34
	class DragonTreasure
	{
	... lines 37 - 132
	public function getPlunderedAtAgo(): string
	{
	return Carbon::instance($this->plunderedAt)->diffForHumans();
	}
	... lines 137 - 148
	}

	... lines 1 - 34
	class DragonTreasure
	{
	... lines 37 - 93
	#[Groups(['treasure:write'])]
	public function setTextDescription(string $description): self
	{
	... lines 97 - 99
	}
	... lines 101 - 150
	}