doc: jsonapi

Author: soyuka

core/jsonapi.md

@@ -0,0 +1,119 @@
+# JSON:API
+
+API Platform supports the [JSON:API](https://jsonapi.org) format. When a client
+sends a request with an `Accept: application/vnd.api+json` header, API Platform
+serializes responses following the JSON:API specification.
+
+For details on enabling formats, see
+[content negotiation](content-negotiation.md).
+
+## Entity Identifiers as Resource IDs
+
+By default, API Platform uses IRIs (Internationalized Resource Identifiers) as
+the `id` field of JSON:API resource objects. For example, a `Dummy` resource with
+database ID `10` has `"id": "/dummies/10"` in the JSON:API response.
+
+The JSON:API specification requires the `id` field to be a string that, combined
+with `type`, uniquely identifies a resource. Using IRIs as IDs is valid, but some
+clients expect plain entity identifiers (such as `"10"`) and use the `links.self`
+field for navigation.
+
+To use entity identifiers instead of IRIs, set `use_iri_as_id` to `false`:
+
+```yaml
+# config/packages/api_platform.yaml
+api_platform:
+    jsonapi:
+        use_iri_as_id: false
+```
+
+### Behavior Changes
+
+When `use_iri_as_id` is `false`:
+
+- **Resource `id`**: Uses the entity identifier (e.g., `"10"`) instead of the IRI
+  (e.g., `"/dummies/10"`).
+- **`links.self`**: Added to each resource object, pointing to the IRI.
+- **Relationships**: Related resources are referenced by entity identifier and
+  `type` instead of IRI and `type`.
+
+### Default Behavior (`use_iri_as_id: true`)
+
+```json
+{
+    "data": {
+        "id": "/dummies/10",
+        "type": "Dummy",
+        "attributes": {
+            "name": "Dummy #10"
+        },
+        "relationships": {
+            "relatedDummy": {
+                "data": {
+                    "id": "/related_dummies/1",
+                    "type": "RelatedDummy"
+                }
+            }
+        }
+    }
+}
+```
+
+### Entity Identifier Mode (`use_iri_as_id: false`)
+
+```json
+{
+    "data": {
+        "id": "10",
+        "type": "Dummy",
+        "links": {
+            "self": "/dummies/10"
+        },
+        "attributes": {
+            "name": "Dummy #10"
+        },
+        "relationships": {
+            "relatedDummy": {
+                "data": {
+                    "id": "1",
+                    "type": "RelatedDummy"
+                }
+            }
+        }
+    }
+}
+```
+
+### Composite Identifiers
+
+Resources with composite identifiers use a semicolon-separated string as the `id`
+value (e.g., `"field1=val1;field2=val2"`).
+
+### Resources Without a Standalone Item Endpoint
+
+When using entity identifier mode, API Platform must resolve the IRI for any
+resource that appears in a relationship. If a resource has no standalone `GET` item
+endpoint (for example, it is only exposed as a subresource), IRI resolution fails.
+
+Use the `NotExposed` operation to register a URI template for internal IRI
+resolution without exposing a public endpoint. A `NotExposed` operation registers
+the route internally but returns a `404` response when accessed directly:
+
+```php
+<?php
+
+namespace App\Entity;
+
+use ApiPlatform\Metadata\NotExposed;
+
+#[NotExposed(uriTemplate: '/tags/{id}')]
+class Tag
+{
+    public int $id;
+    public string $label;
+}
+```
+
+This allows a parent resource to reference `Tag` objects in its relationships
+while `Tag` itself has no public item endpoint. The `NotExposed` operation
+requires a `uriTemplate` with a single URI variable.

outline.yaml

@@ -47,6 +47,7 @@ chapters:
       - validation
       - security
       - content-negotiation
+      - jsonapi
       - pagination
       - deprecations
       - default-order