diff --git a/core/configuration.md b/core/configuration.md index 5b2ff83a8db..87a6725c495 100644 --- a/core/configuration.md +++ b/core/configuration.md @@ -276,6 +276,14 @@ api_platform: # ... + serializer: + # Use the "hydra:" prefix. + hydra_prefix: false + + # Expose the operations sharing the IRI of a resource in the "hydra:operation" property of its + # JSON-LD representations, filtered by their security, unless the operation sets "hydraOperations". + hydra_operations: true + # Global resources defaults, see in the next section. defaults: # ... @@ -687,6 +695,14 @@ return [ 'jsonproblem' => ['mime_types' => ['application/problem+json']], ], + 'serializer' => [ + // Use the "hydra:" prefix. + 'hydra_prefix' => false, + // Expose the operations sharing the IRI of a resource in the "hydra:operation" property of its + // JSON-LD representations, filtered by their security, unless the operation sets "hydraOperations". + 'hydra_operations' => true, + ], + // Global resources defaults, see in the next section. 'defaults' => [ 'pagination_enabled' => true, diff --git a/core/extending-jsonld-context.md b/core/extending-jsonld-context.md index a832704fad7..55d2bf6a17d 100644 --- a/core/extending-jsonld-context.md +++ b/core/extending-jsonld-context.md @@ -209,3 +209,97 @@ This assertion is generated automatically for every collection and isn't configu > `range` array). `owl:equivalentClass` no longer appears anywhere in the generated Hydra > documentation: if you parse `range` and expect that structure, read `hydra:memberAssertion` > instead. + +### The `hydra:operation` Property + +Following [Hydra](https://www.hydra-cg.com/spec/latest/core/#adding-affordances-to-representations), +JSON-LD representations expose the operations a client can perform on them in their +`hydra:operation` property (`operation` without the `hydra:` prefix). By default, every item and +collection exposes all the operations sharing its IRI, filtered by their `security`: a client only +discovers the operations it's allowed to call. Each operation is described as in the +`hydra:supportedOperation` property of the API documentation. For instance, with a `Book` resource +declaring a `Get` and a `Delete` operation, `GET /books/1` returns: + +```json +{ + "@context": "/contexts/Book", + "@id": "/books/1", + "@type": "Book", + "operation": [ + { + "@type": ["Operation", "schema:FindAction"], + "description": "Retrieves a Book resource.", + "method": "GET", + "returns": "Book", + "title": "getBook" + }, + { + "@type": ["Operation", "schema:DeleteAction"], + "description": "Deletes the Book resource.", + "method": "DELETE", + "returns": "owl:Nothing", + "title": "deleteBook" + } + ], + "title": "Hyperion" +} +``` + +To narrow this list, pass `HydraOperation` references to the `hydraOperations` option of an +operation. A reference points to an operation declared on the resource, either by its `name` or by +its `method` and `uriTemplate` (the format suffix is ignored, and the URI template of the current +operation is used when omitted). Referencing an operation that doesn't exist throws an exception. A +reference can also have its own `security`, otherwise the one of the referenced operation is used: + +```php + [ + 'hydra_operations' => false, + ], +]; +``` diff --git a/core/upgrade-guide.md b/core/upgrade-guide.md index 398d95bafa8..4ac36a7deb2 100644 --- a/core/upgrade-guide.md +++ b/core/upgrade-guide.md @@ -1,5 +1,17 @@ # Upgrade Guide +## API Platform 5.0 to 5.1 + +### API Platform 5.1 Behavioral Changes + +#### JSON-LD Representations Expose Their Operations + +JSON-LD items and collections now expose the operations sharing their IRI, filtered by their +security, in a `hydra:operation` property (`operation` without the `hydra:` prefix). Use the +`hydraOperations` option of an operation to narrow or remove them, or set the +`serializer.hydra_operations` configuration to `false` to keep the previous responses. See +[The `hydra:operation` Property](extending-jsonld-context.md#the-hydraoperation-property). + ## API Platform 4.4 to 5.0 5.0 removes long-deprecated APIs. Components ship with a `@beta` stability flag (for example