Chapters

28 Chapters | 2:51:42 |

01

Installing API Platform

7:29
02

Creating your First ApiResource

5:44
03

Swagger UI: Interactive Docs

6:41
04

The Powerful OpenAPI Spec

5:24
05

JSON-LD: Giving Meaning to your Data

7:21
06

Hydra: Describing API Classes, Operations & More

4:06
07

API Debugging with the Profiler

5:12
08

Operations / Endpoints

6:38
09

The Serializer

9:08
10

Serialization Groups: Choosing Fields

7:28
11

Serialization Tricks

5:15
12

Pagination & Foundry Fixtures

5:44
13

Filters: Searching Results

5:14
14

PropertyFilter: Sparse Fieldsets

6:55
15

More Formats: HAL & CSV

7:10
16

Validation

5:29
17

Creating a User Entity

4:06
18

User API Resource

5:51
19

Relating Resources

7:08
20

Relations & Iris

3:40
21

Embedded Relations

5:58
22

Embedded Write

7:29
23

Adding Items to a Collection Property

4:04
24

Creating Embedded Objects

5:34
25

Removing Items from a Collection

3:49
26

Filtering on Relations

3:51
27

Subresources

9:54
28

React Admin

9:20

> APIs > API Platform 3 Part 1: Mythically Good RESTful APIs

Buy Access to Course

21.

Embedded Relations

Autoplay

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 Challenge

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

So when two resources are related in our API, they show up as an IRI string, or collection of strings. But you might wonder:

Hey, could we include the DragonTreasure data right here instead of the IRI so that I don't need to make a second, third or fourth request to get that data?

Absolutely! And, again, you can also do something really cool with Vulcain... but let's learn how to embed data.

Embedding Vs IRI via Normalization Groups

When the User object is being serialized, it uses the normalization groups to determine which fields to include. In this case, we have one group called user:read. That's why email, username and dragonTreasures are all returned.

            Copy Code

                            Show All Lines

                        172 lines
            |
            src/Entity/User.php
        
                Show Lines

                                                    // ... lines 1 - 16
                            
            #[ApiResource(
        
                normalizationContext: ['groups' => ['user:read']],
        
                Show Lines

                                                    // ... line 19
                            
            )]
        
                Show Lines

                                                    // ... lines 21 - 22
                            
            class User implements UserInterface, PasswordAuthenticatedUserInterface
        
            {
        
                Show Lines

                                                    // ... lines 25 - 30
                            
                #[Groups(['user:read', 'user:write'])]
        
                Show Lines

                                                    // ... lines 32 - 33
                            
                private ?string $email = null;
        
                Show Lines

                                                    // ... lines 35 - 46
                            
                #[Groups(['user:read', 'user:write'])]
        
                Show Lines

                                                    // ... line 48
                            
                private ?string $username = null;
        
                Show Lines

                                                    // ... lines 50 - 51
                            
                #[Groups(['user:read'])]
        
                private Collection $dragonTreasures;
        
                Show Lines

                                                    // ... lines 54 - 170
                            
            }

To transform the dragonTreasures property into embedded data, we need to go into DragonTreasure and add this same user:read group to at least one field. Watch: above name, add user:read. Then... go down and also add this for value.

            Copy Code

                            Show All Lines

                        211 lines
            |
            src/Entity/DragonTreasure.php
        
                Show Lines

                                                    // ... lines 1 - 51
                            
            class DragonTreasure
        
            {
        
                Show Lines

                                                    // ... lines 54 - 59
                            
                #[Groups(['treasure:read', 'treasure:write', 'user:read'])]
        
                Show Lines

                                                    // ... lines 61 - 63
                            
                private ?string $name = null;
        
                Show Lines

                                                    // ... lines 65 - 75
                            
                #[Groups(['treasure:read', 'treasure:write', 'user:read'])]
        
                Show Lines

                                                    // ... lines 77 - 78
                            
                private ?int $value = 0;
        
                Show Lines

                                                    // ... lines 80 - 209
                            
            }

Yup, as soon as we have even one property inside of DragonTreasure that's in the user:read normalization group, the way the dragonTreasures field looks will totally change.

Watch: when we execute that... awesome! Instead of an array of IRI strings, it's an array of objects, with name and value... and of course the normal @id and @type fields.

So: when you have a relation field, it will either be represented as an IRI string or an object... and this depends entirely on your normalization groups.

Embedding the Other Direction

Let's try this same thing in the other direction. We have a treasure whose id is 2. Head up to the GET a single treasure endpoint... try it... and enter 2 for the id.

No surprise, we see owner as an IRI string. Could we turn that into an embedded object instead? Of course! We know that DragonTreasure uses the treasure:read normalization group. So, go into User and add that to the username property: treasure:read.

            Copy Code

                            Show All Lines

                        172 lines
            |
            src/Entity/User.php
        
                Show Lines

                                                    // ... lines 1 - 22
                            
            class User implements UserInterface, PasswordAuthenticatedUserInterface
        
            {
        
                Show Lines

                                                    // ... lines 25 - 46
                            
                #[Groups(['user:read', 'user:write', 'treasure:read'])]
        
                Show Lines

                                                    // ... line 48
                            
                private ?string $username = null;
        
                Show Lines

                                                    // ... lines 50 - 170
                            
            }

With just that change... when we try it... yes! The owner field just got transformed into an embedded object!

Embedded for One Endpoint, IRI for Another

Ok, let's also fetch a collection of treasures: just request all of them. Thanks to the change we just made, every single treasure's owner property is now an object.

That gives me a wild, hare-brained idea. What if having all the owner information when I fetch a single DragonTreasure is cool... but maybe it feels like overkill to have that data returned from the collection endpoint. Could we embed the owner when fetching a single treasure... but then use the IRI string when fetching a collection?

The answer is... no! I'm kidding - of course! We can do whatever crazy things we want! Though, the more weird things you add to your API, the trickier life gets. So choose your adventures wisely!

Doing this is a two-step process. First in DragonTreasure, find the Get operation, which is the operation for fetching a single treasure. One of the options that you can pass into an operation is the normalizationContext... which will override the default. Add normalizationContext, then groups set to the standard treasure:read. Then add a second group that's specific to this operation: treasure:item:get.

            Copy Code

                            Show All Lines

                        215 lines
            |
            src/Entity/DragonTreasure.php
        
                Show Lines

                                                    // ... lines 1 - 25
                            
            #[ApiResource(
        
                Show Lines

                                                    // ... lines 27 - 28
                            
                operations: [
        
                    new Get(
        
                        normalizationContext: [
        
                            'groups' => ['treasure:read', 'treasure:item:get'],
        
                        ],
        
                    ),
        
                Show Lines

                                                    // ... lines 35 - 38
                            
                ],
        
                Show Lines

                                                    // ... lines 40 - 53
                            
            )]
        
                Show Lines

                                                    // ... line 55
                            
            class DragonTreasure
        
            {
        
                Show Lines

                                                    // ... lines 58 - 213
                            
            }

You can call this whatever you want... but I like this convention: resource name followed by item or collection then the HTTP method, like get or post.

And yes, I did forget the groups key: I'll fix that in a minute.

Anyways, if I had coded this correctly, it would mean that when this operation is used, the serializer will include all fields that are in at least one of these two groups.

Now we can leverage that. Copy the new group name. Then, over in User, above username, instead of treasure:read, paste that new group.

            Copy Code

                            Show All Lines

                        172 lines
            |
            src/Entity/User.php
        
                Show Lines

                                                    // ... lines 1 - 22
                            
            class User implements UserInterface, PasswordAuthenticatedUserInterface
        
            {
        
                Show Lines

                                                    // ... lines 25 - 46
                            
                #[Groups(['user:read', 'user:write', 'treasure:item:get'])]
        
                Show Lines

                                                    // ... line 48
                            
                private ?string $username = null;
        
                Show Lines

                                                    // ... lines 50 - 170
                            
            }

Let's check it out! Try the GET collection endpoint again. Yes! We're back to owner being an IRI string. And if we try the GET one endpoint.. oh, the owner is... also an IRI here too? That's my bad. Back on normalization_context I forgot to say groups. I was basically setting two meaningless options into normalization_context.

Let's try that again. This time... got it!

When you get fancy like this, it does get a bit harder to keep track of what serialization groups are being used and when. Though you can use the Profiler to help with that. For example, this is our most recent request for the single treasure.

If we open the profiler for that request... and go down to the Serializer section, we see the data that's being serialized... but more importantly the normalization context... including groups set to the two we expect.

This is also cool because you can see other context options that are set by API Platform. These control certain internal behavior.

Next: let's get crazy with our relationships by using a DragonTreasure endpoint to change the username field of that treasure's owner. Woh.

9 Comments

Sort By

Julien-H 8 months ago edited

Hi, someone else know why normalizationContext & denormalizationContext don't work with Symfony 7 et API Plateform 3.2 ?

When i add this :

#[ApiResource(
	shortName: 'Pokemon',
	description: 'The Pokemon List',
	operations: [
		new Get(uriTemplate: '/pokemon/{id}'),
		new GetCollection(uriTemplate: '/pokemon'),
		new Post(uriTemplate: '/pokemon/{id}'),
		new Put(uriTemplate: '/pokemon/{id}'),
		new Patch(uriTemplate: '/pokemon/{id}'),
		new Delete(uriTemplate: '/pokemon/{id}'),
	],
	normalizationContext: ['groups' => ['pokemon']],
	denormalizationContext: ['groups' => ['pokemon']]
)]

API Platform return to me :

 "@id": "/api/errors/500",
  "@type": "hydra:Error",
  "title": "An error occurred",
  "detail": "Attempted to load class \"ClassMetadataInfo\" from namespace \"Doctrine\\ORM\\Mapping\".\nDid you forget a \"use\" statement for another namespace?",
  "status": 500,
  "type": "/errors/500",
  "trace": [
    {
      "file": "/var/www/symfony/vendor/api-platform/core/src/Doctrine/Orm/Extension/EagerLoadingExtension.php",
      "line": 98,
      "function": "joinRelations",
      "class": "ApiPlatform\\Doctrine\\Orm\\Extension\\EagerLoadingExtension",
      "type": "->"
    },

If i remove normalization i have :

    {
      "@id": "/api/pokemon/1",
      "@type": "Pokemon",
      "id": 1,
      "name": "bulbasaur",
      "height": 0.7,
      "weight": 6.9,
      "baseExperience": 64,
      "types": [
        "/api/types/1",
        "/api/types/2"
      ]
    },

My entity :

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Put;
use ApiPlatform\Metadata\Link;
use ApiPlatform\Metadata\Post;
use Doctrine\DBAL\Types\Types;
use ApiPlatform\Metadata\Patch;
use ApiPlatform\Metadata\Delete;
use ApiPlatform\Metadata\ApiResource;
use App\Repository\PokemonRepository;
use ApiPlatform\Metadata\GetCollection;
use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Serializer\Annotation\SerializedName;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
use ApiPlatform\Metadata\ApiFilter;

#[ORM\Entity(repositoryClass: PokemonRepository::class)]
#[ApiResource(
	shortName: 'Pokemon',
	description: 'The Pokemon List',
	operations: [
		new Get(uriTemplate: '/pokemon/{id}'),
		new GetCollection(uriTemplate: '/pokemon'),
		new Post(uriTemplate: '/pokemon/{id}'),
		new Put(uriTemplate: '/pokemon/{id}'),
		new Patch(uriTemplate: '/pokemon/{id}'),
		new Delete(uriTemplate: '/pokemon/{id}'),
	],
	normalizationContext: ['groups' => ['pokemon']],
	denormalizationContext: ['groups' => ['pokemon']]
)]
class Pokemon
{
	/**
	 * The ID of the Pokemon
	 */
	#[ORM\Id]
	#[ORM\GeneratedValue]
	#[ORM\Column]
	private ?int $id = null;

	/**
	 * The Name of the Pokemon
	 */
	#[ORM\Column(length: 255)]
	private ?string $name = null;

	/**
	 * The Height of the Pokemon
	 */
	#[ORM\Column]
	private ?float $height = null;

	/**
	 * The Weight of the Pokemon
	 */
	#[ORM\Column]
	private ?float $weight = null;

	/**
	 * The Base Experience of the Pokemon
	 */
	#[ORM\Column]
	private ?int $baseExperience = null;

	/**
	 * The Types of the Pokemon
	 */
	#[ORM\ManyToMany(targetEntity: Type::class, inversedBy: 'pokemons')]
	private Collection $types;

	public function __construct()
	{
		$this->types = new ArrayCollection();
	}

	public function getId(): ?int
	{
		return $this->id;
	}

	public function getName(): ?string
	{
		return $this->name;
	}

	public function setName(string $name): static
	{
		$this->name = $name;

		return $this;
	}

	public function getHeight(): ?float
	{
		return $this->height;
	}

	public function setHeight(float $height): static
	{
		$this->height = $height;

		return $this;
	}

	public function getWeight(): ?float
	{
		return $this->weight;
	}

	public function setWeight(float $weight): static
	{
		$this->weight = $weight;

		return $this;
	}

	public function getBaseExperience(): ?int
	{
		return $this->baseExperience;
	}

	public function setBaseExperience(int $baseExperience): static
	{
		$this->baseExperience = $baseExperience;

		return $this;
	}

	/**
	 * @return Collection<int, Type>
	 */
	public function getTypes(): Collection
	{
		return $this->types;
	}

	public function addType(Type $type): static
	{
		if (!$this->types->contains($type)) {
			$this->types->add($type);
		}

		return $this;
	}

	public function removeType(Type $type): static
	{
		$this->types->removeElement($type);

		return $this;
	}
}

Thanks a lot !

| Reply |

weaverryan SFCASTS Julien-H 8 months ago

Hey @Carlos-33!

This smells like it's related to the new Doctrine ORM 3 and DBAL version 4. I believe API Platform 3.2.16 should now work... which was just released 2 days ago https://github.com/api-platform/core/releases/tag/v3.2.16

Let me know if that helps! If it doesn't, you can try to downgrade to ORM 2 and DBAL 3 in your composer.json.

Cheers!

| Reply |

Julien-H weaverryan 8 months ago

Hi, working fine thanks !

| Reply |

Carlos-33 1 year ago edited

Hi everyone! I'm currently using the API Platform for my personal project. However, I'm facing an issue. I have three entity relations, which means three levels of embedded relations with normalizationContext groups. The problem is that I can only retrieve data object from the 2 stages. The format of the third stage is a URI and not object.

| Reply |

sadikoff SFCASTS Carlos-33 1 year ago

Hi @Carlos-33,

Interesting, as far as I know there is no limit... is it 3 different entities? Can you re-check if 3rd entity has correct group set on fields you want to read, if it's like a Tree with single entity try #[MaxDepth(2)] attribute to configure serialisation process

Cheers!

| Reply |

Jeremy 1 year ago edited

Hi! Thank you for all these awesome courses! I love it, I stopped my netflix subscription as I prefer to chill on SymfonyCast ;)

Aren't serialization groups going whild when you have to add role access to differents fields of the entity, when you have several roles (admin / seller / customer / public...)? How do you deal with this? Isn't it starting to be a mess in Entities? And when your API is growing with 10 or 20 entities with relations that you need to embed? Maybe you don't embed anymore and rely on Vulcain in this case?

Cheers

Edit : Oh sorry I was in too much of a hurry, all my questions seems to have an answer in the next part : https://symfonycasts.com/screencast/api-platform-security
Thank you very much

| Reply |

Victor SFCASTS Jeremy 1 year ago

Hey Jeremy!

Haha, I hope SymfonyCasts is more interesting for you ;)

So it seems you found the answers in the next chapters - great, I'm happy to hear it :)

Cheers!

| Reply |

Jean-tilapin 1 year ago

Hello there!
Quick question when you have some extra time.
In your exact configuration, when you make a PUT request on the USER, to change for example its username, what do you get in the response, specifically in the embedded collection? Do you get the extra fields you configured or just the IRIs of the treasures owned by the User?
In my very similar case, when I GET the parent, it works just fine, the extra fields of the Children are there. But when I update the parent entity, the configurated fields of the children are systemically replaced by the unique IRIs, breaking all the UI using those fields (for example an Image I display using its name).
I really don't get what I'm doing wrong and don't find where to look for my mistake.
Thanks :)

| Reply |

weaverryan SFCASTS Jean-tilapin 1 year ago

Hi Jean!

I might know the problem you're referring to! Are you, like we do in this chapter, adding an extra (de)normalization group for one specific operation? Like, in this chapter, we add treasure:item:get to just the Get operation. Are you doing something like that?

If so, the problem is that when you make a GET request, it will (of course) normalize with the extra group - e.g. treasure:item:get. But when you make a PUT request, it will first look for the denormalization groups to "read" the JSON you're sending. Then it will look on the Put operation to see what normalization groups it should use. If you've set things up like we did in this chapter, then the Put request will NOT have the extra treasure:item:get. The solution would be to add that extra group also to the PUT operation. Heck, if you care enough, you might even add it to the Post operation so that the extra fields are returned even after you "create" a resource.

Let me know if that's the problem - I wondered while I was recording this if that would trick some people.

Cheers!

| Reply |

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
    }
}

Previous Chapter

Next Challenge

Embedded Relations

Share this awesome video!

Keep on Learning!

Embedding Vs IRI via Normalization Groups

Embedding the Other Direction

Embedded for One Endpoint, IRI for Another

9 Comments

Delete comment?

What PHP libraries does this tutorial use?

Show Lines	// ... lines 1 - 16
	#[ApiResource(
	normalizationContext: ['groups' => ['user:read']],
Show Lines	// ... line 19
	)]
Show Lines	// ... lines 21 - 22
	class User implements UserInterface, PasswordAuthenticatedUserInterface
	{
Show Lines	// ... lines 25 - 30
	#[Groups(['user:read', 'user:write'])]
Show Lines	// ... lines 32 - 33
	private ?string $email = null;
Show Lines	// ... lines 35 - 46
	#[Groups(['user:read', 'user:write'])]
Show Lines	// ... line 48
	private ?string $username = null;
Show Lines	// ... lines 50 - 51
	#[Groups(['user:read'])]
	private Collection $dragonTreasures;
Show Lines	// ... lines 54 - 170
	}

Show Lines	// ... lines 1 - 51
	class DragonTreasure
	{
Show Lines	// ... lines 54 - 59
	#[Groups(['treasure:read', 'treasure:write', 'user:read'])]
Show Lines	// ... lines 61 - 63
	private ?string $name = null;
Show Lines	// ... lines 65 - 75
	#[Groups(['treasure:read', 'treasure:write', 'user:read'])]
Show Lines	// ... lines 77 - 78
	private ?int $value = 0;
Show Lines	// ... lines 80 - 209
	}

Show Lines	// ... lines 1 - 22
	class User implements UserInterface, PasswordAuthenticatedUserInterface
	{
Show Lines	// ... lines 25 - 46
	#[Groups(['user:read', 'user:write', 'treasure:read'])]
Show Lines	// ... line 48
	private ?string $username = null;
Show Lines	// ... lines 50 - 170
	}

Show Lines	// ... lines 1 - 25
	#[ApiResource(
Show Lines	// ... lines 27 - 28
	operations: [
	new Get(
	normalizationContext: [
	'groups' => ['treasure:read', 'treasure:item:get'],
	],
	),
Show Lines	// ... lines 35 - 38
	],
Show Lines	// ... lines 40 - 53
	)]
Show Lines	// ... line 55
	class DragonTreasure
	{
Show Lines	// ... lines 58 - 213
	}