From db4918be09c024dfae973908c9eadd5a7dda550a Mon Sep 17 00:00:00 2001
From: Vincent Chalamon <vincentchalamon@protonmail.com>
Date: Tue, 9 Aug 2022 17:35:07 +0200
Subject: [PATCH 1/2] docs: explain itemUriTemplate option

---
 core/getting-started.md |  4 +-
 core/operations.md      | 94 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 2 deletions(-)

diff --git a/core/getting-started.md b/core/getting-started.md
index 694214a1124..14e4fc5f8f0 100644
--- a/core/getting-started.md
+++ b/core/getting-started.md
@@ -183,7 +183,7 @@ resources:
 <?xml version="1.0" encoding="UTF-8" ?>
 <!-- api/config/api_platform/resources.xml -->
 
-<resource xmlns="https://api-platform.com/schema/metadata/resources-3.0"
+<resources xmlns="https://api-platform.com/schema/metadata/resources-3.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
         https://api-platform.com/schema/metadata/resources-3.0.xsd">
@@ -196,7 +196,7 @@ resources:
         <types>
             <type>https://schema.org/Offer</type> <!-- optional -->
         </types>
-    </resource>
+    </resources>
 </resources>
 ```
 
diff --git a/core/operations.md b/core/operations.md
index 6753a31c900..fd65718b056 100644
--- a/core/operations.md
+++ b/core/operations.md
@@ -440,6 +440,100 @@ book_post_publication:
         _api_operation_name: post_publication
 ```
 
+## Defining Which Operation to Use to Generate the Iri
+
+Using multiple operations on your resource, you may want to specify which operation to use to generate the IRI, instead
+of letting API Platform use the first one it finds.
+
+Let's say you have 2 resources in relationship: Company and User, where a company has multiple users. You can declare
+the following routes:
+
+- `/users`
+- `/users/{id}`
+- `/companies/{companyId}/users`
+- `/companies/{companyId}/users/{id}`
+
+The first routes (`/users...`) are only accessible by the admin, and the others by regular users. Calling
+`/companies/{companyId}/users` should return IRIs matching `/companies/{companyId}/users/{id}` to don't expose an admin
+route to regular users.
+
+To do so, use the `itemUriTemplate` option only available on GetCollection and Post operations:
+
+[codeSelector]
+
+```php
+<?php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Post;
+
+#[GetCollection] // auto-generated path will be /users
+#[Get] // auto-generated path will be /users/{id}
+#[GetCollection(uriTemplate: '/companies/{companyId}/users', itemUriTemplate: '/companies/{companyId}/users/{id}'/*, ... */)]
+#[Post(uriTemplate: '/companies/{companyId}/users', itemUriTemplate: '/companies/{companyId}/users/{id}'/*, ... */)]
+#[Get(uriTemplate: '/companies/{companyId}/users/{id}'/*, ... */)]
+class User
+{
+    //...
+}
+```
+
+```yaml
+# api/config/api_platform/resources.yaml
+resources:
+    App\Entity\Book:
+        - operations:
+            ApiPlatform\Metadata\GetCollection: ~
+            ApiPlatform\Metadata\Get: ~
+        - operations:
+            ApiPlatform\Metadata\GetCollection:
+                uriTemplate: /companies/{companyId}/users
+                itemUriTemplate: /companies/{companyId}/users/{id}
+                # ...
+            ApiPlatform\Metadata\Post:
+                uriTemplate: /companies/{companyId}/users
+                itemUriTemplate: /companies/{companyId}/users/{id}
+                # ...
+            ApiPlatform\Metadata\Get:
+                uriTemplate: /companies/{companyId}/users/{id}
+                # ...
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- api/config/api_platform/resources.xml -->
+
+<resources xmlns="https://api-platform.com/schema/metadata/resources-3.0"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
+        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" />
+        </operations>
+    </resource>
+
+    <resource class="App\Entity\Book">
+        <operations>
+            <operation class="ApiPlatform\Metadata\GetCollection" uriTemplate="/companies/{companyId}/users" itemUriTemplate="/companies/{companyId}/users/{id}" />
+            <operation class="ApiPlatform\Metadata\Post" uriTemplate="/companies/{companyId}/users" itemUriTemplate="/companies/{companyId}/users/{id}" />
+            <operation class="ApiPlatform\Metadata\Get" uriTemplate="/companies/{companyId}/users/{id}" />
+        </operations>
+    </resource>
+</resources>
+```
+
+[/codeSelector]
+
+API Platform will find the operation matching this `itemUriTemplate` and use it to generate the IRI.
+
+If this option is not set, the first Get operation is used to generate the IRI.
+
 ## Expose a Model Without Any Routes
 
 Sometimes, you may want to expose a model, but want it to be used through subrequests only, and never through item or collection operations.

From c74ae516792288beb6693caf3496d9bb67d8c489 Mon Sep 17 00:00:00 2001
From: Vincent <vincentchalamon@protonmail.com>
Date: Tue, 9 Aug 2022 18:06:51 +0200
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: Alan Poulain <contact@alanpoulain.eu>
---
 core/operations.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/core/operations.md b/core/operations.md
index fd65718b056..5ac8969d9d1 100644
--- a/core/operations.md
+++ b/core/operations.md
@@ -440,12 +440,12 @@ book_post_publication:
         _api_operation_name: post_publication
 ```
 
-## Defining Which Operation to Use to Generate the Iri
+## Defining Which Operation to Use to Generate the IRI
 
 Using multiple operations on your resource, you may want to specify which operation to use to generate the IRI, instead
 of letting API Platform use the first one it finds.
 
-Let's say you have 2 resources in relationship: Company and User, where a company has multiple users. You can declare
+Let's say you have 2 resources in relationship: `Company` and `User`, where a company has multiple users. You can declare
 the following routes:
 
 - `/users`
@@ -454,10 +454,10 @@ the following routes:
 - `/companies/{companyId}/users/{id}`
 
 The first routes (`/users...`) are only accessible by the admin, and the others by regular users. Calling
-`/companies/{companyId}/users` should return IRIs matching `/companies/{companyId}/users/{id}` to don't expose an admin
+`/companies/{companyId}/users` should return IRIs matching `/companies/{companyId}/users/{id}` to not expose an admin
 route to regular users.
 
-To do so, use the `itemUriTemplate` option only available on GetCollection and Post operations:
+To do so, use the `itemUriTemplate` option only available on `GetCollection` and `Post` operations:
 
 [codeSelector]
 
@@ -532,7 +532,7 @@ resources:
 
 API Platform will find the operation matching this `itemUriTemplate` and use it to generate the IRI.
 
-If this option is not set, the first Get operation is used to generate the IRI.
+If this option is not set, the first `Get` operation is used to generate the IRI.
 
 ## Expose a Model Without Any Routes