You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
By default, only the [JSON-LD](https://json-ld.org) format is enabled. However API Platform supports many more formats and can be extended.
7
+
By default, only the [JSON-LD](https://json-ld.org) format is enabled. However
8
+
API Platform supports many more formats and can be extended.
6
9
7
-
The framework natively supports JSON-LD (and Hydra), GraphQL, JSON:API, HAL, YAML, CSV, HTML (API docs), raw JSON and raw XML.
8
-
Using the raw JSON or raw XML formats is discouraged, prefer using JSON-LD instead, which provides more feature and is as easy to use.
10
+
The framework natively supports JSON-LD (and Hydra), GraphQL, JSON:API, HAL,
11
+
YAML, CSV, HTML (API docs), raw JSON and raw XML. Using the raw JSON or raw XML
12
+
formats is discouraged, prefer using JSON-LD instead, which provides more
13
+
feature and is as easy to use.
9
14
10
-
API Platform also supports [JSON Merge Patch (RFC 7396)](https://tools.ietf.org/html/rfc7396) the JSON:API[`PATCH`](https://jsonapi.org/format/#crud-updating) formats, as well as [Problem Details (RFC 7807)](https://tools.ietf.org/html/rfc7807), [Hydra](https://www.hydra-cg.com/spec/latest/core/#description-of-http-status-codes-and-errors) and [JSON:API](https://jsonapi.org/format/#errors) error formats.
15
+
API Platform also supports
16
+
[JSON Merge Patch (RFC 7396)](https://tools.ietf.org/html/rfc7396) the JSON:API
17
+
[`PATCH`](https://jsonapi.org/format/#crud-updating) formats, as well as
and [JSON:API](https://jsonapi.org/format/#errors) error formats.
11
21
12
22
<palign="center"class="symfonycasts"><ahref="https://symfonycasts.com/screencast/api-platform/formats?cid=apip"><imgsrc="../symfony/images/symfonycasts-player.png"alt="Formats screencast"><br>Watch the Formats screencast</a></p>
13
23
14
24
API Platform will automatically detect the best resolving format depending on:
15
25
16
26
- enabled formats (see below)
17
-
- the requested format, specified in either [the `Accept` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) or as an extension appended to the URL
|[YAML](https://yaml.org/)|`yaml`|`application/yaml`| no |
39
+
|[YAML](https://yaml.org/)|`yaml`|`application/yaml`| no |
28
40
|[CSV](https://tools.ietf.org/html/rfc4180)|`csv`|`text/csv`| no |
29
41
|[HTML](https://whatwg.org/) (API docs) |`html`|`text/html`| no |
30
42
|[XML](https://www.w3.org/XML/)|`xml`|`application/xml`, `text/xml`| no |
31
43
|[JSON](https://www.json.org/)|`json`|`application/json`| no |
32
44
33
-
If the client's requested format is not specified, the response format will be the first format defined in the `formats` configuration key (see below).
34
-
If the request format is not supported, an [Unsupported Media Type](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/415) error will be returned.
45
+
If the client's requested format is not specified, the response format will be
46
+
the first format defined in the `formats` configuration key (see below). If the
47
+
request format is not supported, an
48
+
[Unsupported Media Type](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/415)
49
+
error will be returned.
35
50
36
-
Examples showcasing how to use the different mechanisms are available [in the API Platform test suite](https://github.com/api-platform/core/blob/main/features/main/content_negotiation.feature).
51
+
Examples showcasing how to use the different mechanisms are available
52
+
[in the API Platform test suite](https://github.com/api-platform/core/blob/main/features/main/content_negotiation.feature).
37
53
38
54
## Configuring Formats Globally
39
55
40
-
The first required step is to configure allowed formats. The following configuration will enable the support of XML (built-in)
41
-
and of a custom format called `myformat` and having `application/vnd.myformat` as [MIME type](https://en.wikipedia.org/wiki/Media_type).
56
+
The first required step is to configure allowed formats. The following
57
+
configuration will enable the support of XML (built-in) and of a custom format
58
+
called `myformat` and having `application/vnd.myformat` as
To enable GraphQL support, [read the dedicated chapter](graphql.md).
59
77
60
-
Because the Symfony Serializer component is able to serialize objects in XML, sending an `Accept` HTTP header with the
61
-
`text/xml`string as value is enough to retrieve XML documents from our API. However API Platform knows nothing about the
62
-
`myformat`format. We need to register an encoder and optionally a normalizer for this format.
78
+
Because the Symfony Serializer component is able to serialize objects in XML,
79
+
sending an `Accept` HTTP header with the `text/xml` string as value is enough to
80
+
retrieve XML documents from our API. However API Platform knows nothing about
81
+
the `myformat` format. We need to register an encoder and optionally a
82
+
normalizer for this format.
63
83
64
84
## Configuring PATCH Formats
65
85
66
86
By default, API Platform supports JSON Merge Patch and JSON:API PATCH formats.
67
-
Support for the JSON:API PATCH format is automatically enabled if JSON:API support is enabled.
68
-
JSON Merge Patch support must be enabled explicitly:
87
+
Support for the JSON:API PATCH format is automatically enabled if JSON:API
88
+
support is enabled. JSON Merge Patch support must be enabled explicitly:
69
89
70
90
```yaml
71
91
# api/config/packages/api_platform.yaml
72
92
api_platform:
73
93
patch_formats:
74
-
json: ['application/merge-patch+json']
75
-
jsonapi: ['application/vnd.api+json']
94
+
json: ["application/merge-patch+json"]
95
+
jsonapi: ["application/vnd.api+json"]
76
96
```
77
97
78
-
When support for at least one PATCH format is enabled, [an `Accept-Patch` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Patch) containing the list of supported patch formats is automatically added to all HTTP responses for items.
98
+
When support for at least one PATCH format is enabled,
containing the list of supported patch formats is automatically added to all
101
+
HTTP responses for items.
79
102
80
103
## Configuring Error Formats
81
104
82
-
API Platform will try to send to the client the error format matching with the format request with the `Accept` HTTP headers (or the URL extension). For instance, if a client request a JSON-LD representation of a resource, and an error occurs, then API Platform will serialize this error using the Hydra format (Hydra is a vocabulary for JSON-LD containing a standard representation of API errors).
105
+
API Platform will try to send to the client the error format matching with the
106
+
format request with the `Accept` HTTP headers (or the URL extension). For
107
+
instance, if a client request a JSON-LD representation of a resource, and an
108
+
error occurs, then API Platform will serialize this error using the Hydra format
109
+
(Hydra is a vocabulary for JSON-LD containing a standard representation of API
## Configuring Formats For a Specific Resource or Operation
96
124
97
-
Support for specific formats can also be configured at resource and operation level using the `inputFormats` and `outputFormats` attributes.
98
-
`inputFormats`controls the formats accepted in request bodies while `outputFormats` controls formats available for responses.
125
+
Support for specific formats can also be configured at resource and operation
126
+
level using the `inputFormats` and `outputFormats` attributes. `inputFormats`
127
+
controls the formats accepted in request bodies while `outputFormats` controls
128
+
formats available for responses.
99
129
100
-
The `format` attribute can be used as a shortcut, it sets both the `inputFormats` and `outputFormats` in one time.
130
+
The `format` attribute can be used as a shortcut, it sets both the
131
+
`inputFormats`and `outputFormats` in one time.
101
132
102
133
```php
103
134
<?php
@@ -113,13 +144,16 @@ class Book
113
144
}
114
145
```
115
146
116
-
In the example above, `xml` or `jsonld` will be allowed and there is no need to specify the MIME types as they are already defined in the configuration.
147
+
In the example above, `xml` or `jsonld` will be allowed and there is no need to
148
+
specify the MIME types as they are already defined in the configuration.
117
149
Additionally the `csv` format is added with the MIME type `text/csv`.
118
150
119
-
It is also important to notice that the usage of this attribute will override the formats defined in the configuration, therefore
120
-
this configuration might disable the `json` or the `html` on this resource for example.
151
+
It is also important to notice that the usage of this attribute will override
152
+
the formats defined in the configuration, therefore this configuration might
153
+
disable the `json` or the `html` on this resource for example.
121
154
122
-
You can specify different accepted formats at operation level too, it's especially convenient to configure formats available for the `PATCH` method:
155
+
You can specify different accepted formats at operation level too, it's
156
+
especially convenient to configure formats available for the `PATCH` method:
123
157
124
158
<code-selector>
125
159
@@ -148,12 +182,14 @@ class Book
148
182
resources:
149
183
App\Entity\Book:
150
184
formats:
151
-
0: 'jsonld' # format already defined in the config
152
-
csv: 'text/csv'
185
+
0: "jsonld" # format already defined in the config
186
+
csv: "text/csv"
153
187
operations:
154
188
ApiPlatform\Metadata\Get:
155
189
formats:
156
-
json: ['application/merge-patch+json'] # works also with "application/merge-patch+json"
190
+
json: [
191
+
"application/merge-patch+json",
192
+
] # works also with "application/merge-patch+json"
157
193
```
158
194
159
195
```xml
@@ -182,9 +218,10 @@ resources:
182
218
183
219
## Supporting Custom Formats
184
220
185
-
The API Platform content negotiation system is extendable.
186
-
You can add support for formats not available by default by creating custom normalizers and encoders.
187
-
Refer to the Symfony documentation to learn [how to create and register such classes](https://symfony.com/doc/current/serializer.html#adding-normalizers-and-encoders).
221
+
The API Platform content negotiation system is extendable. You can add support
222
+
for formats not available by default by creating custom normalizers and
223
+
encoders. Refer to the Symfony documentation to learn
224
+
[how to create and register such classes](https://symfony.com/doc/current/serializer.html#adding-normalizers-and-encoders).
188
225
189
226
Then, register the new format in the configuration:
190
227
@@ -193,36 +230,39 @@ Then, register the new format in the configuration:
193
230
api_platform:
194
231
formats:
195
232
# ...
196
-
myformat: ['application/vnd.myformat']
233
+
myformat: ["application/vnd.myformat"]
197
234
```
198
235
199
236
You will also need to declare an encoder which supports the new format:
200
237
201
238
```yaml
202
239
services:
203
-
app.api-platform.myformat.encoder:
204
-
class: ApiPlatform\Serializer\JsonEncoder
205
-
arguments:
206
-
$format: 'myformat'
207
-
# The following lines are only needed if autoconfigure is disabled
208
-
# tags:
209
-
# - { name: 'serializer.encoder' }
240
+
app.api-platform.myformat.encoder:
241
+
class: ApiPlatform\Serializer\JsonEncoder
242
+
arguments:
243
+
$format: "myformat"
244
+
# The following lines are only needed if autoconfigure is disabled
245
+
# tags:
246
+
# - { name: 'serializer.encoder' }
210
247
```
211
248
212
-
API Platform will automatically call the serializer with your defined format name as `format` parameter during the deserialization process (`myformat` in the example).
213
-
It will then return the result to the client with the requested MIME type using its built-in responder.
214
-
For non-standard formats, [a vendor, vanity or unregistered MIME type should be used](https://en.wikipedia.org/wiki/Media_type#Vendor_tree).
249
+
API Platform will automatically call the serializer with your defined format
250
+
name as `format` parameter during the deserialization process (`myformat` in the
251
+
example). It will then return the result to the client with the requested MIME
252
+
type using its built-in responder. For non-standard formats,
253
+
[a vendor, vanity or unregistered MIME type should be used](https://en.wikipedia.org/wiki/Media_type#Vendor_tree).
215
254
216
255
### Reusing the API Platform Infrastructure
217
256
218
-
Using composition is the recommended way to implement a custom normalizer. You can use the following template to start your
219
-
own implementation of `CustomItemNormalizer`:
257
+
Using composition is the recommended way to implement a custom normalizer. You
258
+
can use the following template to start your own implementation of
0 commit comments