Newer
Older
Klaranouba7
a validé
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
# Resource Identifiers
* Status: proposed
* Deciders: @dunglas @alanpoulain @soyuka
Technical Story: [#2126][pull/2126]
Implementation: [#3825][pull/3825]
## Context and Problem Statement
In API Platform, a resource is identified by [IRIs][rfc/IRI], for example `/books/1`. Internally, this is also known as a route with an identifier parameter named `id`: `/books/{id}`. This `id` parameter is then matched to the resource identifiers, known by the `ApiProperty` metadata when `identifier` is true. When multiple identifiers are found, composite identifiers map the value of `id` to the resource identifiers (eg: `keya=value1;keyb=value2`, where `keya` and `keyb` are identifiers of the resource). This behavior is suggested by the [URI RFC][rfc/URI].
Subresources IRIs have multiple parts, for example: `/books/{id}/author/{authorId}`. The router needs to know that `id` matches the `Book` resource, and `authorId` the `Author` resource. To do so, a Tuple representing the class and the property matching each parameter is linked to the route, for example: `id: [Book, id], authorId: [User, id]`.
By normalizing the shape of (sub-)resources (see [0000-subresources-definition][0000-subresources-definition]), we need to normalize the resource identifiers.
## Decision Outcome
Declare explicit resource `identifiers` that will default to `id: [id, Resource]` with composite identifiers. Allow composite identifiers to be disabled if needed.
### Examples
Define a route `/users/{id}`:
```php
/**
* @ApiResource
*/
class User {
/** @ApiProperty(identifier=true) */
public int $id;
}
```
Or
```php
/**
* @ApiResource(identifiers={"id": {User::class, "id"}})
*/
class User {
/** @ApiProperty(identifier=true) */
public int $id;
}
```
Define a route `/users/{username}` that uses the username identifier:
```php
/**
* @ApiResource(identifiers={"username"})
*/
class User {
/** @ApiProperty(identifier=true) */
public string $username;
}
```
Or
```php
/**
* @ApiResource(identifiers={"username": {User::class, "username"}})
*/
class User {
/** @ApiProperty(identifier=true) */
public string $username;
}
```
Define a route `/users/{username}` that uses the property shortName:
```php
/**
* @ApiResource(identifiers={"username"={User::class, "shortName"}})
*/
class User {
/** @ApiProperty(identifier=true) */
public string $shortName;
}
```
Define a route `/users/{composite}` that uses composite identifiers `/users/keya=value1;keyb=value2`:
```php
/**
* @ApiResource(identifiers={"composite"})
*/
class User {
/** @ApiProperty(identifier=true) */
public string $keya;
/** @ApiProperty(identifier=true) */
public string $keyb;
}
```
Define a route `/users/{keya}/{keyb}`:
```php
/**
* @ApiResource(identifiers={"keya", "keyb"}, compositeIdentifier=false)
*/
class User {
/** @ApiProperty(identifier=true) */
public string $keya;
/** @ApiProperty(identifier=true) */
public string $keyb;
}
```
Complex version:
```php
/**
* @ApiResource(identifiers={"keya"={User::class, "keya"}, "keyb"={User::class, "keyb"}}, compositeIdentifier=false)
*/
class User {
/** @ApiProperty(identifier=true) */
public string $keya;
/** @ApiProperty(identifier=true) */
public string $keyb;
}
```
Define a subresource `/companies/{companyId}/users/{id}`:
```php
/**
* @ApiResource(path="/users", identifiers={"id": {User::class, "id"}})
* @ApiResource(path="/companies/{companyId}/users", identifiers={"companyId": {Company::class, "id"}, "id": {User::class, "id"}})
*/
class User {
/** @ApiProperty(identifier=true) */
public int $id;
/** @var Company[] */
public array $companies = [];
}
class Company {
/** @ApiProperty(identifier=true) */
public int $id;
/** @var User[] */
public $users;
}
```
## Links
* Adds up to the [0000-subresources-definition][0000-subresources-definition] rework.
[0000-subresources-definition]: ./0000-subresources-definition "Subresources definition"
[pull/2126]: https://github.com/api-platform/core/pull/2126 "Ability to specify identifier property of custom item operations"
[pull/3825]: https://github.com/api-platform/core/pull/3825 "Rework to improve and simplify identifiers management"
[rfc/IRI]: https://tools.ietf.org/html/rfc3987 "RFC3987"
[rfc/URI]: https://tools.ietf.org/html/rfc3986#section-3.3 "RFC 3986"