ApiFilter and GroupFilter purpose and usage - api-platform.com

Question

I'm trying to grasp the purpose and usage of api filters, and the doc I find on the net is extremely sparse, including "https://api-platform.com/docs/core/filters".
From what I understand, the typeFilters allow the api user to filter according to a given strategy (e.g don't retrieve data where dates are null), right?
Writing a filter annotation on the class level is equivalent to writing it on every property of the targetted type, right?
I'd like to understand the group filter, but there is not one example of that. What am I supposed to understand from the class annotation * #ApiFilter(GroupFilter::class, arguments={"parameterName"="foobargroups"})? foobargroup is not used anywhere else in the codebase. Not within the DummyCar.php example nor in another class, ang google doesn't find me even one working example.
What I need is a way to tell the api to return only a part of the entity or another. Would groupFilter do? Or is that only used to handle 1-N relationship?

Answer 1

Those are serializer filters.
if you have an Entity like
<?php
namespace App\Entity;
use ApiPlatform\Core\Annotation\ApiFilter;
use ApiPlatform\Core\Annotation\ApiProperty;
use ApiPlatform\Core\Annotation\ApiResource;
use ApiPlatform\Core\Serializer\Filter\GroupFilter;
use ApiPlatform\Core\Serializer\Filter\PropertyFilter;
use Symfony\Component\Serializer\Annotation\Groups;
/**
* #ApiResource
* #ApiFilter(PropertyFilter::class)
* #ApiFilter(GroupFilter::class)
*/
class User {
/**
* #Groups({"list"})
*/
public $email;
public $firstname;
public $lastname;
/**
* #Groups({"list"})
*/
public $age;
}
When sending a GET request to /users, the collection in JSON-LD for example should look like
{
...
"hydra:members": [
{
"#id": ...,
"#type": ...,
"email": "john-email#dre.ss",
"firstname": "John",
"lastname": "Doe",
"age": 30
},
{
"#id": ...,
"#type": ...,
"email": "jane-email#dre.ss",
"firstname": "Jane",
"lastname": "Doe",
"age": 20
}
]
...
}
When using the property filter, sending a GET request to /users?properties[]=email&properties[]=firstname, the collection would look like
{
...
"hydra:members": [
{
"#id": ...,
"#type": ...,
"email": "john-email#dre.ss",
"firstname": "John"
},
{
"#id": ...,
"#type": ...,
"email": "jane-email#dre.ss",
"firstname": "Jane"
}
]
...
}
When using the group filter, sending a GET request to /users?groups[]=list, the collection would look like
{
...
"hydra:members": [
{
"#id": ...,
"#type": ...,
"email": "john-email#dre.ss",
"age": 30
},
{
"#id": ...,
"#type": ...,
"email": "jane-email#dre.ss",
"age": 20
}
]
...
}
I hope it helps to understand.
Writing a filter annotation on the class level is equivalent to
writing it on every property of the targetted type, right?
This is true for ORM filter, not serializer filter
Finally, using #ApiFilter(GroupFilter::class, arguments={"parameterName"="foobargroups"}) is to allow you to change the query parameter property if for instance you have a "real" property called groups. Then instead of sending the GET request to /users?groups[]=list, you would send /users?foobargroups[]=list