We use cookies on this site to enhance your user experience. By clicking "OK, I Agree" or using our site, you consent to the use of cookies unless you have disabled them. View our cookie policy to learn more.
OK, I AGREE
TRACK
APIs >
COURSE
API Platform: Serious RESTful APIs
Buy Access to Course

Serialization Groups

Keep on Learning!

If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.

Start your All-Access Pass
Buy just this tutorial for $12.00
Previous Chapter

Next Chapter
Edit on Github

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

Login Subscribe

If the only way to control the input and output of our API was by controlling the getters and setters on our entity, it wouldn't be that flexible... and could be a bit dangerous. You might add a new getter or setter method for something internal and not realize that you were exposing new data in your API!

The solution for this - and the way that I recommend doing things in all cases - is to use serialization groups.

Adding a Group for Normalization

In the annotation, add normalizationContext. Remember, normalization is when you're going from your object to an array. So this option is related to when you are reading data from your API. Context is basically "options" that you pass to that process. The most common option by far is called "groups", which you set to another array. Add one string here: cheese_listing:read.

125 lines src/Entity/CheeseListing.php
... lines 1 - 8
/**
* @ApiResource(
... lines 11 - 16
* normalizationContext={"groups"={"cheese_listing:read"}}
* )
... line 19
*/
class CheeseListing
... lines 22 - 125

Thanks to this, when an object is being serialized, the serializer will only include fields that are in this cheese_listing:read group, because, in a second, we're going to start adding groups to each property.

But right now, we haven't added any groups to anything. And so, if you go over and try your get collection operation... oh! Ah! A huge error!

Debugging Errors

Let's... pretend like I did that on purpose and see how to debug it! The problem is that the giant HTML error is... a bit hard to read. One way to see the error is to use our trick from earlier: go to https://localhost:8000/_profiler/.

Woh! Ok, there are two types of errors: runtime errors, where something went wrong specific to that request, and build errors, where some invalid configuration is killing every page. Most of the time, if you see an exception, there is still a profiler you can find for that request by using the trick of going to this URL, finding that request in the list - usually right on top - and clicking the sha into its profiler. Once you're there, you can click an "Exception" tab on the left to see the big, beautiful normal exception.

If you get a build error that kills every page, it's even easier: you'll see it when trying to access anything.

Anyways, the problem here is with my annotation syntax. I do this a lot - which is no big deal as long as you know how to debug the error. And, yep! I forgot a comma at the end.

Adding Groups to Fields

Refresh again! The profiler works, so now we can go back over and hit execute again. Check it out - we have @id and @type from JSON-LD... but it doesn't contain any real fields because none of them are in the new cheese_listing:read group!

Copy the cheese_listing:read group name. To add fields to this, above title, use @Groups(), {""} and paste. Let's also put that above description... and price.

129 lines src/Entity/CheeseListing.php
... lines 1 - 7
use Symfony\Component\Serializer\Annotation\Groups;
... lines 9 - 21
class CheeseListing
{
... lines 24 - 30
/**
... line 32
* @Groups({"cheese_listing:read"})
*/
private $title;
... line 36
/**
... line 38
* @Groups({"cheese_listing:read"})
*/
private $description;
... line 42
/**
... lines 44 - 46
* @Groups({"cheese_listing:read"})
*/
private $price;
... lines 50 - 127
}

Flip back over and try it again. Beautiful! We get those three exact fields. I love this control.

By the way - the name cheese_listing:read... I just made that up - you could use anything. But, I will be following a group naming convention that I recommend. It'll give you flexibility, but keep things organized.

Adding Denormalization Groups

Now we can do the same thing with the input data. Copy normalizationContext, paste, and add de in front to make denormalizationContext. This time, use the group: cheese_listing:write

130 lines src/Entity/CheeseListing.php
... lines 1 - 9
/**
* @ApiResource(
... lines 12 - 18
* denormalizationContext={"groups"={"cheese_listing:write"}}
* )
... line 21
*/
... lines 23 - 130

Copy that and... let's see... just add this to title and price for now. We actually don't want to add it to description. Instead, we'll talk about how to add this group to the fake textDescription in a minute.

130 lines src/Entity/CheeseListing.php
... lines 1 - 22
class CheeseListing
{
... lines 25 - 31
/**
... line 33
* @Groups({"cheese_listing:read", "cheese_listing:write"})
*/
private $title;
... lines 37 - 43
/**
... lines 45 - 47
* @Groups({"cheese_listing:read", "cheese_listing:write"})
*/
private $price;
... lines 51 - 128
}

Move over and refresh again. Open up the POST endpoint.... yea - the only fields we can pass now are title and price!

So normalizationContext and denormalizationContext are two totally separate configs for the two directions: reading our data - normalization - and writing our data - denormalization.

The Open API Read & Write Models

At the bottom of the docs, you'll also notice that we now have two models: the read model - that's the normalization context with title, description and price, and the write model with title and price.

And, it's not really important, but you can control these names if you want. Add another option: swagger_definition_name set to "Read". And then the same thing below... set to Write.

130 lines src/Entity/CheeseListing.php
... lines 1 - 9
/**
* @ApiResource(
... lines 12 - 17
* normalizationContext={"groups"={"cheese_listing:read"}, "swagger_definition_name"="Read"},
* denormalizationContext={"groups"={"cheese_listing:write"}, "swagger_definition_name"="Write"}
* )
... line 21
*/
... lines 23 - 130

I don't normally care about this, but if you want to control it, you can.

Adding Groups to Fake Fields

But, we're missing some fields! When we read the data, we get back title, description and price. But what about our createdAt field or our custom createdAtAgo field?

Let's pretend that we only want to expose createdAtAgo. No problem! Just add the @Groups annotation to that property... oh wait... there is no createdAtAgo property. Ah, it's just as easy: find the getter and put the annotation there: @Groups({"cheese_listing:read"}). And while we're here, I'll add some documentation to that method:

How long ago in text that this cheese listing was added.

135 lines src/Entity/CheeseListing.php
... lines 1 - 22
class CheeseListing
{
... lines 25 - 112
/**
* How long ago in text that this cheese listing was added.
*
* @Groups("cheese_listing:read")
*/
public function getCreatedAtAgo(): string
... lines 119 - 133
}

Let's try it! Refresh the docs. Down in the models section... nice! There's our new createdAtAgo readonly field. And that documentation we added shows up here. Nice! No surprise that when we try it... the field shows up.

For denormalization - for sending data - we need to re-add our fake textDescription field. Search for the setTextDescription() method. To prevent API clients from sending us the description field directly, we removed the setDescription() method. Above setTextDescription(), add @Groups({"cheese_listing:write"}). And again, let's give this some extra docs.

140 lines src/Entity/CheeseListing.php
... lines 1 - 88
/**
* The description of the cheese as raw text.
*
* @Groups("cheese_listing:write")
*/
public function setTextDescription(string $description): self
... lines 95 - 140

This time, when we refresh the docs, you can see it on the write model and, of course, on the data that we can send to the POST operation.

Have Whatever Getters and Setters You Want

And... this leads us to some great news! If we decide that something internally in our app does need to set the description property directly, it's now perfectly ok to re-add the original setDescription() method. That won't become part of our API.

147 lines src/Entity/CheeseListing.php
... lines 1 - 88
public function setDescription(string $description): self
{
$this->description = $description;
return $this;
}
... lines 95 - 147

Default isPublished Value

Let's try all of this out. Refresh the docs page. Let's create a new listing: Delicious chèvre - excuse my French - for $25 and a description with some line breaks. Execute!

Woh! A 500 error! I could go look at this exception in the profiler, but this one is pretty easy to read: an exception in our query: is_published cannot be null. Oh, that makes sense: the user isn't sending is_published... so nobody is setting it. And it's set to not null in the database. No worries: default the property to false.

147 lines src/Entity/CheeseListing.php
... lines 1 - 22
class CheeseListing
{
... lines 25 - 59
private $isPublished = false;
... lines 61 - 145
}

Tip

Actually, the auto-validation was not enabled by default in Symfony 4.3, but may be in Symfony 4.4.

By the way, if you're using Symfony 4.3, instead of a Doctrine error, you may have gotten a validation error. That's due to a new feature where Doctrine database constraints can automatically be used to add validation. So, if you see a validation error, awesome!

Anyways, try to execute it again. It works! We have exactly the input fields and output fields that we want. The isPublished field isn't exposed at all in our API, but it is being set in the background.

Next, let's learn a few more serialization tricks - like how to control the field name and how to handle constructor arguments.

Leave a comment!

  • 2019-08-12 weaverryan

    Hey Eric!

    Nice work! And I see that it HAS gotten some good attention - open source in action!

  • 2019-08-07 Eric

    Gotcha. I've done just that and provided a detailed outline on https://github.com/api-plat... with a link and description on how to reproduce the issue. Thanks!

  • 2019-08-06 weaverryan

    Hey Eric!

    Ah, boo! I was hoping traits might work! Thanks for opening the issue - I just saw it. If you REALLY want to motivate action on it, create a new Symfony project (composer create-project symfony/skeleton api_platform_bug), install API platform and see if you can reproduce the bug with the *minimum* amount of code possible. Then, push that to GitHub on its own repo and link to it from the issue. I can say from experience that when there is a very technical issue like this, it means that *someone* will need to take the time to actually take the code from the issue and try to create a "reproducer". Because everyone is so busy, it's unlikely a maintainer will be able to do that. If *you* can do it, it helps a lot :).

    Cheers!

  • 2019-08-05 Eric

    Hi Ryan! Just tried traits and I'm experiencing the same issue. I've gone ahead and opened an issue here: https://github.com/api-plat.... Thanks!

  • 2019-08-05 weaverryan

    Hey Eric!

    Hmmm. This is really-well explained... and the behavior is strange enough that I'm pretty sure this is caused by a bug somewhere in API Platform. Could you open an issue on their repo with all this information (or also with a small app pushed to GitHub which shows the bug? https://github.com/api-plat...

    As a workaround, you could consider using traits (I'm assuming they won't have the same bug): put someProperty in a trait and "use" it from your entities. This may or may not work depending on exactly what you're trying to accomplish. But based on the code you showed here, it should work.

    Let me know!

    Cheers!

  • 2019-08-02 Eric

    I've noticed the documentation (https://api-platform.com/do... indicates that when serialization groups are specified at an operation level they should take precedence over the configuration specified at the resource level. This makes sense and seems to work fine when your entity does not extend from another class.

    Example of what works: Notice that I have resource level normalizationContext and denormalizationContext defined per the tutorial. But I modified the POST operation to have serialization group of "create" and have applied that group to the $description property. This works as expected and the Swagger docs generate everything correctly (model section has a "cheeses-create" definition and the $description property is defined).


    namespace App\Entity;

    use ApiPlatform\Core\Annotation\ApiFilter;
    use ApiPlatform\Core\Annotation\ApiResource;
    use ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\BooleanFilter;
    use ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\SearchFilter;
    use ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\RangeFilter;
    use ApiPlatform\Core\Serializer\Filter\PropertyFilter;
    use Symfony\Component\Validator\Constraints as Assert;
    use Carbon\Carbon;
    use Doctrine\ORM\Mapping as ORM;
    use Symfony\Component\Serializer\Annotation\Groups;
    use Symfony\Component\Serializer\Annotation\SerializedName;

    /**
     * @ApiResource(
     *      collectionOperations={
     *          "get",
     *          "post"={
     *              "normalization_context"={"groups"={"create"}},
     *              "denormalization_context"={"groups"={"create"}},
     *          }
     *      },
     *      itemOperations={
     *          "get",
     *          "put"
     *      },
     *     normalizationContext={"groups"={"cheese_listing:read"}, "swagger_definition_name"="Read"},
     *     denormalizationContext={"groups"={"cheese_listing:write"}, "swagger_definition_name"="Write"},
     *     shortName="cheeses",
     *     attributes={
     *          "pagination_items_per_page"=2,
     *          "formats"={"jsonld", "json", "html", "jsonhal", "csv"={"text/csv"}}
     *     }
     * )
     * @ApiFilter(BooleanFilter::class, properties={"isPublished"})
     * @ApiFilter(SearchFilter::class, properties={"title": "partial", "description": "partial"})
     * @ApiFilter(RangeFilter::class, properties={"price"})
     * @ApiFilter(PropertyFilter::class)
     * @ORM\Entity(repositoryClass="App\Repository\CheeseListingRepository")
     */
    class CheeseListing extends BaseEntity
    {
        /**
         * @ORM\Id()
         * @ORM\GeneratedValue()
         * @ORM\Column(type="integer")
         */
        private $id;

        /**
         * @Assert\NotBlank()
         * @Assert\Length(
         *     min=2,
         *     max=50,
         *     maxMessage="Describe your cheese in 50 chars or less"
         * )
         * @Groups({"cheese_listing:read", "cheese_listing:write"})
         * @ORM\Column(type="string", length=255)
         */
        private $title;

        /**
         * @Assert\NotBlank()
         * @Groups({"cheese_listing:read", "create"})
         * @ORM\Column(type="text")
         */
        private $description;

    But, if I have my CheeseListing extend BaseEntity and the BaseEntity class contains a property that has a serialization group of "create", it does not show up if I keep my CheeseListing as defined above. BUT if I remove the resource level normalizationContext and denormalizationContext lines it shows up then... so not sure why it is completely being ignored.

    The 2 lines I needed to remove to get the "create" serialization group to show up for the POST operation. But... with removing those, I now lose my Read and Write definitions and groups.


     *     normalizationContext={"groups"={"cheese_listing:read"}, "swagger_definition_name"="Read"},
     *     denormalizationContext={"groups"={"cheese_listing:write"}, "swagger_definition_name"="Write"},

    My BaseEntity.php file:


    namespace App\Entity;

    use Symfony\Component\Serializer\Annotation\Groups;

    class BaseEntity
    {
        /**
         * @Groups({"create"})
         */
        protected $someProperty;

        public function getSomeProperty()
        {
            return $this->someProperty;
        }

        public function setSomeProperty($someProperty): void
        {
            $this->someProperty = $someProperty;
        }
    }

    Any idea why I need to remove the resource level normalization and denormalization contexts to get groups in parent classes to show up?

  • 2019-07-24 weaverryan

    Hey David Wilson!

    Hmm... that's an excellent point - and unfortunate :/. Just to make sure I understand, this is the XML version of the OpenAPI spec that's generated?

    Cheers!

  • 2019-07-24 David Wilson

    one concern about the naming convention for serialization groups, if you enable XML and use swagger, it does not like the colon in the serialization groups:

    <user-user:write>
    <email>[email protected]</email>
    </user-user:write>

    Returns:
    Namespace prefix User-user on write is not defined

  • 2019-07-01 Diego Aguiar

    Hey Sasa Milivojevic

    It should be the same, just don't forget to include your imports and add a namespace to your trait

    Cheers!

  • 2019-06-29 Sasa Milivojevic

    Hi, how to add some field to groups if we are using traits?

  • 2019-06-12 Victor Bocharsky

    Hey John,

    You're totally right, we forgot to show the namespace in the code block, I fixed it in https://github.com/SymfonyC... - the correct code block will be available very soon on the website.

    Thank you for reporting it!

    Cheers!

  • 2019-06-11 John Christensen

    To get the @Groups annotation to work, I had to add this use statement:

    use Symfony\Component\Serializer\Annotation\Groups;

    Unless I missed something earlier, that step should be added to the Adding a Group for Normalization section.

Edit on Github
Previous Chapter
Next Chapter