Skip to content

docs(core/operations): update explanation about omitting GET item operation #2212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: 4.2
Choose a base branch
from
Open

docs(core/operations): update explanation about omitting GET item operation #2212

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fbf8a02
docs(core/operations): update explanation about omitting GET item ope…
ttskch Sep 22, 2025
62f8d67
tweak
ttskch Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 67 additions & 54 deletions core/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,18 @@ resources:
API Platform is smart enough to automatically register the applicable Symfony route referencing a built-in CRUD action
just by specifying the method name as key, or by checking the explicitly configured HTTP method.

If you do not want to allow access to the resource item (i.e. you don't want a `GET` item operation), instead of omitting it altogether, you should instead declare a `GET` item operation which returns HTTP 404 (Not Found), so that the resource item can still be identified by an IRI. For example:
By default, API Platform uses the first `Get` operation defined to generate the IRI of an item and the first `GetCollection` operation to generate the IRI of a collection.

If your resource does not have any `Get` operation, API Platform automatically adds an operation to help generating this IRI.
If your resource has any identifier, this operation will look like `/books/{id}`. But if your resource doesn’t have any identifier, API Platform will use the Skolem format `/.well-known/genid/{id}`.
Those routes are not exposed from any documentation (for instance OpenAPI), but are anyway declared on the routing system and always return a HTTP 404.

## Configuring Operations

The URL, the method and the default status code (among other options) can be configured per operation.

In the next example, both `GET` and `POST` operations are registered with custom URLs. Those will override the URLs generated by default.
In addition to that, we require the `id` parameter in the URL of the `GET` operation to be an integer, and we configure the status code generated after successful `POST` request to be `301`:

<code-selector>

Expand All @@ -198,22 +209,27 @@ If you do not want to allow access to the resource item (i.e. you don't want a `
// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Action\NotFoundAction;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Post;

#[ApiResource(operations: [
new Get(
controller: NotFoundAction::class,
read: false,
output: false
uriTemplate: '/grimoire/{id}',
requirements: ['id' => '\d+'],
defaults: ['color' => 'brown'],
options: ['my_option' => 'my_option_value'],
schemes: ['https'],
host: '{subdomain}.api-platform.com'
),
new GetCollection()
new Post(
uriTemplate: '/grimoire',
status: 301
)
])]
class Book
{
// ...
//...
}
```

Expand All @@ -222,11 +238,19 @@ class Book
resources:
App\Entity\Book:
operations:
ApiPlatform\Metadata\GetCollection: ~
ApiPlatform\Metadata\Post:
uriTemplate: '/grimoire'
status: 301
ApiPlatform\Metadata\Get:
controller: ApiPlatform\Action\NotFoundAction
read: false
output: false
uriTemplate: '/grimoire/{id}'
requirements:
id: '\d+'
defaults:
color: 'brown'
host: '{subdomain}.api-platform.com'
schemes: ['https']
options:
my_option: 'my_option_value'
```

```xml
Expand All @@ -239,22 +263,33 @@ resources:
https://api-platform.com/schema/metadata/resources-3.0.xsd">
<resource class="App\Entity\Book">
<operations>
<operation class="ApiPlatform\Metadata\GetCollection" />
<operation class="ApiPlatform\Metadata\Get" controller="ApiPlatform\Action\NotFoundAction"
read="false" output="false" />
<operation class="ApiPlatform\Metadata\Post" uriTemplate="/grimoire" status="301" />
<operation class="ApiPlatform\Metadata\Get" uriTemplate="/grimoire/{id}" host="{subdomain}.api-platform.com">
<requirements>
<requirement property="id">\d+</requirement>
</requirements>
<defaults>
<values>
<value name="color">brown</value>
</values>
</defaults>
<schemes>
<scheme>https</scheme>
</schemes>
<options>
<values>
<value name="color">brown</value>
</values>
</options>
</operation>
</operations>
</resource>
</resources>
```

</code-selector>

## Configuring Operations

The URL, the method and the default status code (among other options) can be configured per operation.

In the next example, both `GET` and `POST` operations are registered with custom URLs. Those will override the URLs generated by default.
In addition to that, we require the `id` parameter in the URL of the `GET` operation to be an integer, and we configure the status code generated after successful `POST` request to be `301`:
When you do not want to allow access to the resource item (i.e. you don't want a `GET` item operation), instead of omitting the resource item altogether, you can explicitly specify the IRI of the resource item by declaring a `GET` item operation that returns HTTP 404 (Not Found). For example:

<code-selector>

Expand All @@ -263,18 +298,17 @@ In addition to that, we require the `id` parameter in the URL of the `GET` opera
// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Action\NotFoundAction;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Post;

#[ApiResource(operations: [
new Get(
uriTemplate: '/grimoire/{id}',
requirements: ['id' => '\d+'],
defaults: ['color' => 'brown'],
options: ['my_option' => 'my_option_value'],
schemes: ['https'],
host: '{subdomain}.api-platform.com'
controller: NotFoundAction::class,
read: false,
output: false
),
new Post(
uriTemplate: '/grimoire',
Expand All @@ -283,7 +317,7 @@ use ApiPlatform\Metadata\Post;
])]
class Book
{
//...
// ...
}
```

Expand All @@ -297,14 +331,9 @@ resources:
status: 301
ApiPlatform\Metadata\Get:
uriTemplate: '/grimoire/{id}'
requirements:
id: '\d+'
defaults:
color: 'brown'
host: '{subdomain}.api-platform.com'
schemes: ['https']
options:
my_option: 'my_option_value'
controller: ApiPlatform\Action\NotFoundAction
read: false
output: false
```

```xml
Expand All @@ -318,24 +347,8 @@ resources:
<resource class="App\Entity\Book">
<operations>
<operation class="ApiPlatform\Metadata\Post" uriTemplate="/grimoire" status="301" />
<operation class="ApiPlatform\Metadata\Get" uriTemplate="/grimoire/{id}" host="{subdomain}.api-platform.com">
<requirements>
<requirement property="id">\d+</requirement>
</requirements>
<defaults>
<values>
<value name="color">brown</value>
</values>
</defaults>
<schemes>
<scheme>https</scheme>
</schemes>
<options>
<values>
<value name="color">brown</value>
</values>
</options>
</operation>
<operation class="ApiPlatform\Metadata\Get" uriTemplate="/grimoire/{id}"
controller="ApiPlatform\Action\NotFoundAction" read="false" output="false" />
</operations>
</resource>
</resources>
Expand Down
10 changes: 1 addition & 9 deletions symfony/messenger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,10 @@ namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Post;
use Symfony\Component\Validator\Constraints as Assert;
use ApiPlatform\Action\NotFoundAction;

#[ApiResource(operations: [
new Get(controller: NotFoundAction::class, read: false, status: 404),
new Post(messenger: true, output: false, status: 202)
])]
final class Person
Expand All @@ -56,18 +53,13 @@ resources:
status: 202
messenger: true
output: false
ApiPlatform\Metadata\Get:
status: 404
controller: ApiPlatform\Action\NotFoundAction
read: false
```

</code-selector>

Because the `messenger` attribute is `true`, when a `POST` is handled by API Platform, the corresponding instance of the `Person` will be dispatched.

For this example, only the `POST` operation is enabled. We disabled the item operation using the `NotFoundAction`. A resource must have at least one item operation as it must be identified by an IRI, here the route `/people/1` exists, eventhough it returns a 404 status code.
We use the `status` attribute to configure API Platform to return a [202 Accepted HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202).
For this example, only the `POST` operation is enabled. If the resource does not have any `Get` operation, API Platform [automatically adds an operation to help generating an IRI identify the resource](../core/operations/#enabling-and-disabling-operations). We use the `status` attribute to configure API Platform to return a [202 Accepted HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202).
It indicates that the request has been received and will be treated later, without giving an immediate return to the client.
Finally, the `output` attribute is set to `false`, so the HTTP response that will be generated by API Platform will be empty, and the [serialization process](../core/serialization.md) will be skipped.

Expand Down