From 107a62447dc56d23177d24eb01af55faf7f21b1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20H=C3=A9bert?= Date: Tue, 24 Sep 2024 14:17:06 +0200 Subject: [PATCH 1/4] fix (images): Use relative links for the symfonycast player --- core/content-negotiation.md | 2 +- core/extending-jsonld-context.md | 4 ++-- core/extending.md | 2 +- core/filters.md | 2 +- core/getting-started.md | 2 +- core/index.md | 2 +- core/jwt.md | 2 +- core/openapi.md | 2 +- core/operations.md | 2 +- core/pagination.md | 2 +- core/security.md | 2 +- core/serialization.md | 8 ++++---- core/testing.md | 2 +- core/validation.md | 2 +- deployment/index.md | 2 +- distribution/debugging.md | 2 +- distribution/index.md | 2 +- distribution/testing.md | 2 +- extra/contribution-guides.md | 2 +- 19 files changed, 23 insertions(+), 23 deletions(-) diff --git a/core/content-negotiation.md b/core/content-negotiation.md index e80792a5d2b..7eadcd6b3e6 100644 --- a/core/content-negotiation.md +++ b/core/content-negotiation.md @@ -9,7 +9,7 @@ Using the raw JSON or raw XML formats is discouraged, prefer using JSON-LD inste 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. -

Formats screencast
Watch the Formats screencast

+

Formats screencast
Watch the Formats screencast

API Platform will automatically detect the best resolving format depending on: diff --git a/core/extending-jsonld-context.md b/core/extending-jsonld-context.md index 1ef4eb6b10d..2724aa471d9 100644 --- a/core/extending-jsonld-context.md +++ b/core/extending-jsonld-context.md @@ -2,7 +2,7 @@ ## JSON-LD -

JSON-LD screencast
Watch the JSON-LD screencast

+

JSON-LD screencast
Watch the JSON-LD screencast

API Platform provides the possibility to extend the JSON-LD context of properties. This allows you to describe JSON-LD-typed values, inverse properties using the `@reverse` keyword and you can even overwrite the `@id` property this way. Everything you define @@ -63,7 +63,7 @@ Note that you do not have to provide the `@id` attribute. If you do not provide ## Hydra -

Hydra screencast
Watch the Hydra screencast

+

Hydra screencast
Watch the Hydra screencast

It's also possible to replace the Hydra context used by the documentation generator: diff --git a/core/extending.md b/core/extending.md index 345b6652bc0..c38b26e3c12 100644 --- a/core/extending.md +++ b/core/extending.md @@ -35,4 +35,4 @@ For instance, if you want to send a mail after a resource has been persisted, bu To replace existing API Platform services with your decorators, [check out how to decorate services](https://symfony.com/doc/current/service_container/service_decoration.html). -

Service Decoration screencast
Watch the Service Decoration screencast

+

Service Decoration screencast
Watch the Service Decoration screencast

diff --git a/core/filters.md b/core/filters.md index 3df1d2a77c1..67eda76a7a3 100644 --- a/core/filters.md +++ b/core/filters.md @@ -12,7 +12,7 @@ By default, all filters are disabled. They must be enabled explicitly. When a filter is enabled, it automatically appears in the [OpenAPI](openapi.md) and [GraphQL](graphql.md) documentations. It is also automatically documented as a `hydra:search` property for JSON-LD responses. -

Filtering and Searching screencast
Watch the Filtering & Searching screencast

+

Filtering and Searching screencast
Watch the Filtering & Searching screencast

## Parameters diff --git a/core/getting-started.md b/core/getting-started.md index e0c284c8853..ec462033433 100644 --- a/core/getting-started.md +++ b/core/getting-started.md @@ -30,7 +30,7 @@ and what [JSON-LD](https://json-ld.org/) and [Hydra](https://www.hydra-cg.com/) ## Mapping the Entities -

Create an API Resource screencast
Watch the Create an API Resource screencast

+

Create an API Resource screencast
Watch the Create an API Resource screencast

API Platform is able to automatically expose entities mapped as "API resources" through a REST API supporting CRUD operations. diff --git a/core/index.md b/core/index.md index 9ffe95681f3..659e61edea1 100644 --- a/core/index.md +++ b/core/index.md @@ -43,6 +43,6 @@ This bundle is extensively tested (unit and functional). The [`Fixtures/` direct ## Screencasts -

SymfonyCasts, API Platform screencasts

+

SymfonyCasts, API Platform screencasts

The easiest and funniest way to learn how to use API Platform is to watch [the more than 60 screencasts available on SymfonyCasts](https://symfonycasts.com/tracks/rest?cid=apip#api-platform-3)! diff --git a/core/jwt.md b/core/jwt.md index a8f49813ad6..b79eeae919e 100644 --- a/core/jwt.md +++ b/core/jwt.md @@ -7,7 +7,7 @@ The tokens are signed by the server's key, so the server is able to verify that API Platform allows to easily add a JWT-based authentication to your API using [LexikJWTAuthenticationBundle](https://github.com/lexik/LexikJWTAuthenticationBundle). -

JWT screencast
Watch the LexikJWTAuthenticationBundle screencast

+

JWT screencast
Watch the LexikJWTAuthenticationBundle screencast

## Installing LexikJWTAuthenticationBundle diff --git a/core/openapi.md b/core/openapi.md index eda7f12e2e5..9371a21cff0 100644 --- a/core/openapi.md +++ b/core/openapi.md @@ -4,7 +4,7 @@ API Platform natively supports the [OpenAPI](https://www.openapis.org/) API spec ![Screenshot](../distribution/images/swagger-ui-1.png) -

OpenAPI screencast
Watch the OpenAPI screencast

+

OpenAPI screencast
Watch the OpenAPI screencast

The specification of the API is available at the `/docs.jsonopenapi` path. By default, OpenAPI v3 is used. diff --git a/core/operations.md b/core/operations.md index 6d22d337483..e49d196da59 100644 --- a/core/operations.md +++ b/core/operations.md @@ -3,7 +3,7 @@ API Platform relies on the concept of operations. Operations can be applied to a resource exposed by the API. From an implementation point of view, an operation is a link between a resource, a route and its related controller. -

Operations screencast
Watch the Operations screencast

+

Operations screencast
Watch the Operations screencast

API Platform automatically registers typical [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations and describes them in the exposed documentation (Hydra and Swagger). It also creates and registers routes corresponding diff --git a/core/pagination.md b/core/pagination.md index 027cc3b7b99..5120a2f34f3 100644 --- a/core/pagination.md +++ b/core/pagination.md @@ -1,6 +1,6 @@ # Pagination -

Pagination screencast
Watch the Pagination screencast

+

Pagination screencast
Watch the Pagination screencast

API Platform has native support for paged collections. Pagination is enabled by default for all collections. Each collection contains 30 items per page. diff --git a/core/security.md b/core/security.md index 5e319221df1..3bc4e892ed0 100644 --- a/core/security.md +++ b/core/security.md @@ -4,7 +4,7 @@ The API Platform security layer is built on top of the [Symfony Security compone All its features, including [global access control directives](https://symfony.com/doc/current/security.html#securing-url-patterns-access-control) are supported. API Platform also provides convenient [access control expressions](https://symfony.com/doc/current/expressions.html#security-complex-access-controls-with-expressions) which you can apply at resource and operation level. -

Security screencast
Watch the Security screencast

+

Security screencast
Watch the Security screencast

diff --git a/core/serialization.md b/core/serialization.md index 8d90c0ebf54..007770de7f2 100644 --- a/core/serialization.md +++ b/core/serialization.md @@ -4,7 +4,7 @@ API Platform embraces and extends the Symfony Serializer Component to transform PHP entities in (hypermedia) API responses. -

Serializer screencast
Watch the Serializer screencast

+

Serializer screencast
Watch the Serializer screencast

The main serialization process has two stages: @@ -32,7 +32,7 @@ JSON-LD, or JavaScript Object Notation for Linked Data, is a method of encoding ## The Serialization Context, Groups and Relations -

Serialization Groups screencast
Watch the Serialization Groups screencast

+

Serialization Groups screencast
Watch the Serialization Groups screencast

API Platform allows you to specify the `$context` variable used by the Symfony Serializer. This variable is an associative array that has a handy `groups` key allowing you to choose which attributes of the resource are exposed during the normalization (read) and denormalization (write) processes. It relies on the [serialization (and deserialization) groups](https://symfony.com/doc/current/components/serializer.html#attributes-groups) @@ -300,7 +300,7 @@ Refer to the [operations](operations.md) documentation to learn more. ## Embedding Relations -

Relations screencast
Watch the Relations screencast

+

Relations screencast
Watch the Relations screencast

By default, the serializer provided with API Platform represents relations between objects using [dereferenceable IRIs](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier). They allow you to retrieve details for related objects by issuing extra HTTP requests. However, for performance reasons, it is sometimes preferable to avoid forcing the client to issue extra HTTP requests. @@ -777,7 +777,7 @@ App\Entity\Greeting: ## Changing the Serialization Context Dynamically -

Context Builder & Service Decoration screencast
Watch the Context Builder & Service Decoration screencast

+

Context Builder & Service Decoration screencast
Watch the Context Builder & Service Decoration screencast

Let's imagine a resource where most fields can be managed by any user, but some can be managed only by admin users: diff --git a/core/testing.md b/core/testing.md index e42081f785b..30261b7cbb9 100644 --- a/core/testing.md +++ b/core/testing.md @@ -3,7 +3,7 @@ API Platform provides a set of useful utilities dedicated to API testing. For an overview of how to test an API Platform app, be sure to read [the testing cookbook first](../distribution/testing.md). -

Test and Assertions screencast
Watch the API Tests & Assertions screencast

+

Test and Assertions screencast
Watch the API Tests & Assertions screencast

## The Test HttpClient diff --git a/core/validation.md b/core/validation.md index 407ae9fd64d..16264bddefc 100644 --- a/core/validation.md +++ b/core/validation.md @@ -4,7 +4,7 @@ API Platform takes care of validating the data sent to the API by the client (us By default, the framework relies on [the powerful Symfony Validator Component](https://symfony.com/doc/current/validation.html) for this task, but you can replace it with your preferred validation library such as [the PHP filter extension](https://www.php.net/manual/en/intro.filter.php) if you want to. -

Validation screencast
Watch the Validation screencast

+

Validation screencast
Watch the Validation screencast

## Validating Submitted Data diff --git a/deployment/index.md b/deployment/index.md index b8dc3b07f48..cac63909614 100644 --- a/deployment/index.md +++ b/deployment/index.md @@ -9,7 +9,7 @@ If you want to play with a local Kubernetes cluster, read [how to deploy an API If you don't want to use Docker, keep in mind that the server application of API Platform is a standard Symfony project, while the Progressive Web Application is a standard Next.js project: -

JWT screencast
Watch the Animated Deployment with Ansistrano screencast

+

JWT screencast
Watch the Animated Deployment with Ansistrano screencast

* [Deploying the Symfony application](https://symfony.com/doc/current/deployment.html) * [Deploying the Next.js application](https://nextjs.org/docs/deployment) diff --git a/distribution/debugging.md b/distribution/debugging.md index 0575a303ed2..ea685cd1f6a 100644 --- a/distribution/debugging.md +++ b/distribution/debugging.md @@ -1,6 +1,6 @@ # Debugging -

API Platform debugging screencast
Watch the Debugging API Platform screencast

+

API Platform debugging screencast
Watch the Debugging API Platform screencast

## Xdebug diff --git a/distribution/index.md b/distribution/index.md index b1e9437194c..f63c43055da 100644 --- a/distribution/index.md +++ b/distribution/index.md @@ -800,6 +800,6 @@ and [browse it online](https://demo.api-platform.com). ## Screencasts -

SymfonyCasts, API Platform screencasts

+

SymfonyCasts, API Platform screencasts

The easiest and funniest way to learn how to use API Platform is to watch [the more than 60 screencasts available on SymfonyCasts](https://symfonycasts.com/tracks/rest?cid=apip#api-platform-3)! diff --git a/distribution/testing.md b/distribution/testing.md index 51a00f44421..8870556d967 100644 --- a/distribution/testing.md +++ b/distribution/testing.md @@ -7,7 +7,7 @@ API Platform provides a set of helpful testing utilities to write unit tests, fu Let's learn how to use them! -

Tests and Assertions screencast
Watch the Tests & Assertions screencast

+

Tests and Assertions screencast
Watch the Tests & Assertions screencast

In this article you'll learn how to use: diff --git a/extra/contribution-guides.md b/extra/contribution-guides.md index 17dd84cd79f..ac658d5c8a1 100644 --- a/extra/contribution-guides.md +++ b/extra/contribution-guides.md @@ -7,4 +7,4 @@ **To report a security issue, please refer to [the dedicated document](security.md).** -

JWT screencast
Watch the Contributing back to Symfony screencast (free)

+

JWT screencast
Watch the Contributing back to Symfony screencast (free)

From c54863872fc9d5b34c34e052d8d30e2cdee88ff9 Mon Sep 17 00:00:00 2001 From: Silvio Ney Date: Mon, 23 Sep 2024 12:15:36 +0100 Subject: [PATCH 2/4] Update index.md fix code highlight --- laravel/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/laravel/index.md b/laravel/index.md index f2ede1e2a88..d962205e402 100644 --- a/laravel/index.md +++ b/laravel/index.md @@ -589,7 +589,7 @@ php artisan make:request BookFormRequest Then, add validation rules to the generated class (`app/Http/Requests/BookFormRequest.php` in our example): -```php +```patch namespace App\Http\Requests; use Illuminate\Foundation\Http\FormRequest; From ebeb934faecf8c96d4841d5f9a288d2388917def Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Mon, 23 Sep 2024 14:52:39 +0200 Subject: [PATCH 3/4] laravel: better GraphQL link --- laravel/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/laravel/index.md b/laravel/index.md index d962205e402..0effc240cc1 100644 --- a/laravel/index.md +++ b/laravel/index.md @@ -9,7 +9,7 @@ With API Platform, you can: * [expose your Eloquent](#exposing-a-model) models in minutes as: * a REST API implementing the industry-leading standards, formats and best practices: [JSON-LD](https://en.wikipedia.org/wiki/JSON-LD)/[RDF](https://en.wikipedia.org/wiki/Resource_Description_Framework), [JSON:API](https://jsonapi.org), [HAL](https://stateless.group/hal_specification.html), and many RFCs... - * a [GraphQL](https://graphql.org/) API + * a [GraphQL](#enabling-graphql) API * or both at the same time, with the same code! * automatically expose an [OpenAPI](https://www.openapis.org) specification (formerly Swagger), dynamically generated from your Eloquent models and always up to date * automatically expose nice UIs and playgrounds to develop using your API ([Swagger UI](https://swagger.io/tools/swagger-ui/) and [GraphiQL](https://github.com/graphql/graphiql)) From ed227aafc221f4f0477d1bd15b626245c93cddc3 Mon Sep 17 00:00:00 2001 From: Pieter Oliver <68863060+pieterocp@users.noreply.github.com> Date: Wed, 25 Sep 2024 13:14:51 +0100 Subject: [PATCH 4/4] Fix: Reduce proselint warnings (#1966) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Appease the proselint's moaning about no comma needed in dates ```lint ./extra/releases.md: - dates_times.dates When specifying a month and year, no comma is needed. ``` * Remove weasel word - very ```lint weasel_words.very Substitute 'damn' every time you're inclined to write 'very'; your editor will delete it and the writing will be just as it should be. ``` * Update openapi.md * Update migrate-from-fosrestbundle.md --------- Co-authored-by: Kévin Dunglas --- admin/openapi.md | 12 +++++++----- core/dto.md | 2 +- core/migrate-from-fosrestbundle.md | 16 ++++++++-------- core/subresources.md | 2 +- extra/releases.md | 10 +++++----- 5 files changed, 22 insertions(+), 20 deletions(-) diff --git a/admin/openapi.md b/admin/openapi.md index 23218e2ab79..59fa6f19c47 100644 --- a/admin/openapi.md +++ b/admin/openapi.md @@ -1,8 +1,8 @@ # OpenAPI -API Platform Admin has a native support for API exposing an [OpenAPI documentation](https://www.openapis.org/). +API Platform Admin has native support for API exposing an [OpenAPI documentation](https://www.openapis.org/). -To use it, use the `OpenApiAdmin` component, with the entrypoint of the API and the entrypoint of the OpenAPI documentation in JSON: +To use it, use the `OpenApiAdmin` component, with the entry point of the API and the entry point of the OpenAPI documentation in JSON: ```javascript import { OpenApiAdmin } from "@api-platform/admin"; @@ -12,12 +12,14 @@ export default () => ( ); ``` -**Note:** The OpenAPI documentation needs to follow some assumptions in order to be understood correctly by the underlying `api-doc-parser`. -See the [dedicated part in the `api-doc-parser` library README](https://github.com/api-platform/api-doc-parser#openapi-support). +> [!NOTE] +> +> The OpenAPI documentation needs to follow some assumptions to be understood correctly by the underlying `api-doc-parser`. +> See the [dedicated part in the `api-doc-parser` library README](https://github.com/api-platform/api-doc-parser#openapi-support). ## Data Provider -By default, the component will use a very basic data provider, without pagination support. +By default, the component will use a basic data provider, without pagination support. If you want to use [another data provider](https://marmelab.com/react-admin/DataProviderList.html), pass the `dataProvider` prop to the component: diff --git a/core/dto.md b/core/dto.md index 462a6a8ae17..e9bc870b146 100644 --- a/core/dto.md +++ b/core/dto.md @@ -2,7 +2,7 @@ As stated in [the general design considerations](design.md), in most cases [the DTO pattern](https://en.wikipedia.org/wiki/Data_transfer_object) should be implemented using an API Resource class representing the public data model exposed through the API and [a custom State Provider](state-providers.md). In such cases, the class marked with `#[ApiResource]` will act as a DTO. -However, it's sometimes useful to use a specific class to represent the input or output data structure related to an operation. These techniques are very useful to document your API properly (using Hydra or OpenAPI) and will often be used on `POST` operations. +However, it's sometimes useful to use a specific class to represent the input or output data structure related to an operation. These techniques are useful to document your API properly (using Hydra or OpenAPI) and will often be used on `POST` operations. ## Implementing a Write Operation With an Input Different From the Resource diff --git a/core/migrate-from-fosrestbundle.md b/core/migrate-from-fosrestbundle.md index 3bb3e841293..469a4e56e8c 100644 --- a/core/migrate-from-fosrestbundle.md +++ b/core/migrate-from-fosrestbundle.md @@ -1,9 +1,9 @@ # Migrate From FOSRestBundle [FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle) is a popular bundle to rapidly develop RESTful APIs with Symfony. -This page provides a guide to help developers migrating from FOSRestBundle to API Platform. +This page provides a guide to help developers migrate from FOSRestBundle to API Platform. -[On 21 September, 2021](https://twitter.com/lsmith/status/1440216817876627459), FOSRestBundle's creators recommended to use API Platform. +[On 21 September 2021](https://x.com/lsmith/status/1440216817876627459), FOSRestBundle's creators recommended to use API Platform. ## Features Comparison @@ -13,13 +13,13 @@ The table below provides a list of the main features you can find in FOSRestBund **In FOSRestBundle** -Create a controller extending the `AbstractFOSRestController` abstract class, make your magic manually in your methods and return responses through the `handleView()` provided by FOSRest's `ControllerTrait`. +Create a controller extending the `AbstractFOSRestController` abstract class, make your magic manually in your methods, and return responses through the `handleView()` provided by FOSRest's `ControllerTrait`. See [The view layer](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/2-the-view-layer.rst). **In API Platform** -Add the `ApiResource` attribute to your entities, and enable operations you desire inside. By default, every operations are activated. +Add the `ApiResource` attribute to your entities, and enable the operations you desire inside. By default, every operation is activated. See [Operations](operations.md). @@ -33,7 +33,7 @@ Same as above. Even though this is not recommended, API Platform allows you to [create custom controllers](controllers.md) and declare them in your entity's `ApiResource` attribute. -You can use them as you migrate from FOSRestBundle, but you should consider [switching to Symfony Messenger](messenger.md) as it will give you more benefits, such as compatibility with both REST and GraphQL, and better performances of your API on big tasks. +You can use them as you migrate from FOSRestBundle, but you should consider [switching to Symfony Messenger](messenger.md) as it will give you more benefits, such as compatibility with both REST and GraphQL and better performances of your API on big tasks. See [General Design Considerations](design.md). @@ -52,11 +52,11 @@ Use the `ApiResource` attribute to activate the HTTP methods you need for your e See [Operations](operations.md). -### Hook into the requests handling +### Hook into the handling of the requests **In FOSRestBundle** -Listen to FOSRest's events to modify the requests before they come into your controllers, and the responses after they come out of them. +Listen to FOSRest's events to modify the requests before they come into your controllers and the responses after they come out of them. See [Listener support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/3-listener-support.rst). @@ -140,6 +140,6 @@ See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/ **In API Platform** -API Platform has no native support to API versioning, but instead provides an approach consisting of deprecating resources when needed. It allows a smoother upgrade for clients, as they need to change their code only when it is necessary. +API Platform has no native support for API versioning, but instead provides an approach consisting of deprecating resources when needed. It allows a smoother upgrade for clients, as they need to change their code only when it is necessary. See [Deprecating Resources and Properties](deprecations.md). diff --git a/core/subresources.md b/core/subresources.md index 97f4ab995e0..36734c61335 100644 --- a/core/subresources.md +++ b/core/subresources.md @@ -4,7 +4,7 @@ A Subresource is another way of declaring a resource that usually involves a mor In API Platform you can declare as many `ApiResource` as you want on a PHP class creating Subresources. -Subresources work very well by implementing your own state [providers](./state-providers.md) +Subresources work well by implementing your own state [providers](./state-providers.md) or [processors](./state-processors.md). In API Platform we provide a working Doctrine layer for subresources providing you add the correct configuration for URI Variables. diff --git a/extra/releases.md b/extra/releases.md index 77eb6b842ff..0a26fbf3c9f 100644 --- a/extra/releases.md +++ b/extra/releases.md @@ -5,11 +5,11 @@ A new minor version is released every six months, and a new major version is rel For example: -- version 3.0 has been released on 15 September, 2022; -- version 3.1 has been released on 23 January, 2023; -- version 3.2 has been released on 12 October, 2023; -- version 3.3 has been released on 9 April, 2024 (we were a little late, it should have been published in March); -- versions 3.4 and 4.0 will be released on September, 2024. +- version 3.0 has been released on 15 September 2022; +- version 3.1 has been released on 23 January 2023; +- version 3.2 has been released on 12 October 2023; +- version 3.3 has been released on 9 April 2024 (we were a little late, it should have been published in March); +- versions 3.4 and 4.0 will be released on September 2024. ## Maintenance