From 0d74e044f2cf28539cbe71c9ddd6aad74f3645aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tanghe?= Date: Tue, 2 Nov 2021 12:10:58 +0100 Subject: [PATCH 1/9] docs: add guide to migrate from FOSRestBundle --- core/migration-guides/fosrestbundle.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 core/migration-guides/fosrestbundle.md diff --git a/core/migration-guides/fosrestbundle.md b/core/migration-guides/fosrestbundle.md new file mode 100644 index 00000000000..443a8d2a9b4 --- /dev/null +++ b/core/migration-guides/fosrestbundle.md @@ -0,0 +1,21 @@ +# Migrate From FOSRestBundle + +[FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle) is a popular bundle to rapidly develop RESTful APIs with Symfony. + +In September 2021, [it has been announced to be deprecated](https://twitter.com/lsmith/status/1440216817876627459) and its maintainers recommended to use API Platform instead. This page provides a guide to help developers migrating from FOSRestBundle to API Platform. + +## Features Comparison + +The table below provides a list of the main features you can find in FOSRestBundle 3.1, and their equivalents in API Platform. + +| Feature | FOSRestBundle | API Platform +| --- | --- | --- +| **Make CRUD endpoints** | 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). | Add the `ApiResource` attribute to your entities, and enable operations you desire inside. By default, every operations are activated.
See [Operations](../operations/). +| **Make custom controllers** | Same as above. | Create an invokable class, do your magic inside, and declare it in your entity's `ApiResource`.
See [Creating Custom Operations and Controllers](../controllers/). +| **Routing system** (with native documentation support) | Annotate your controllers with FOSRest's route annotations that are the most suitable to your needs.
See [Full default annotations](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst). | This is handled by the `ApiResource` attribute mentionned above. +| **Hook into the requests handling** | 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). | Listen to Symfony's events to modify the HTTP responses. API Platform provides a lot of constants to help you set priorities correctly.
See [The Event System](../events/). +| **Customize the formats of the requests and the responses** | Only the request body's format can be customized.
Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML.
See [Body Listener](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and the response body's format can be customized.
You can configure the formats of the API either globally or in specific resources or operations. API Platform provides native support for multiple supports including JSON, XML, CSV, YAML, etc.
See [Content negociation](../content-negotiation/). +| **Name conversion** | Only the request bodys can be converted before entering into your controller.
FOSRest provides two native normalizers for converting the names of your JSON keys to camelCase. You can create your own ones by implementing the `ArrayNormalizerInterface`.
See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and response bodys can be converted.
API Platform uses the name converters included in the Serializer compononent of Symfony. You can create your own by implementing the `NameConverterInterface` provided by Symfony.
See [_Name Conversion_ in The Serialization Process](../serialization/#name-conversion). +| **Handle errors** | Map the exeptions to HTTP statuses in the `fos_rest.exception` parameter.
See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst). | Map the exeptions to HTTP statuses in the `api_platform.exception_to_status` parameter.
See [Errors Handling](../errors/). +| **Security** | Use Symfony's security features directly with the `security.yaml` in your controller or the `security.yml` file. | Use the `security` attribute in the `ApiResource` and `ApiProperty` attributes. It is an [Expression language](https://symfony.com/doc/current/components/expression_language/) string describing who can access your resources, and the properties of your resources. By default, everything is accessible without authentication.
Note you can also use the `security.yml` file if you don't need so specific rules.
See [Security](../security/). +| **API versioning** | FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use.
See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst). | API Platform has no native support to API versioning, but instead provide an approach consisting of deprecating resources when needed. This allows a smoother upgrade for clients, as they need to change their code only when it is necessary.
See [Deprecating Resources and Properties](../deprecations/). From 0363853655061ffd240a0e3af516dccdd0a85cbc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Deuchnord?= Date: Tue, 2 Nov 2021 18:28:13 +0100 Subject: [PATCH 2/9] Fix typos Co-authored-by: Alan Poulain --- core/migration-guides/fosrestbundle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core/migration-guides/fosrestbundle.md b/core/migration-guides/fosrestbundle.md index 443a8d2a9b4..4d005aa863e 100644 --- a/core/migration-guides/fosrestbundle.md +++ b/core/migration-guides/fosrestbundle.md @@ -14,8 +14,8 @@ The table below provides a list of the main features you can find in FOSRestBund | **Make custom controllers** | Same as above. | Create an invokable class, do your magic inside, and declare it in your entity's `ApiResource`.
See [Creating Custom Operations and Controllers](../controllers/). | **Routing system** (with native documentation support) | Annotate your controllers with FOSRest's route annotations that are the most suitable to your needs.
See [Full default annotations](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst). | This is handled by the `ApiResource` attribute mentionned above. | **Hook into the requests handling** | 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). | Listen to Symfony's events to modify the HTTP responses. API Platform provides a lot of constants to help you set priorities correctly.
See [The Event System](../events/). -| **Customize the formats of the requests and the responses** | Only the request body's format can be customized.
Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML.
See [Body Listener](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and the response body's format can be customized.
You can configure the formats of the API either globally or in specific resources or operations. API Platform provides native support for multiple supports including JSON, XML, CSV, YAML, etc.
See [Content negociation](../content-negotiation/). +| **Customize the formats of the requests and the responses** | Only the request body's format can be customized.
Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML.
See [Body Listener](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and the response body's format can be customized.
You can configure the formats of the API either globally or in specific resources or operations. API Platform provides native support for multiple formats including JSON, XML, CSV, YAML, etc.
See [Content negociation](../content-negotiation/). | **Name conversion** | Only the request bodys can be converted before entering into your controller.
FOSRest provides two native normalizers for converting the names of your JSON keys to camelCase. You can create your own ones by implementing the `ArrayNormalizerInterface`.
See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and response bodys can be converted.
API Platform uses the name converters included in the Serializer compononent of Symfony. You can create your own by implementing the `NameConverterInterface` provided by Symfony.
See [_Name Conversion_ in The Serialization Process](../serialization/#name-conversion). -| **Handle errors** | Map the exeptions to HTTP statuses in the `fos_rest.exception` parameter.
See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst). | Map the exeptions to HTTP statuses in the `api_platform.exception_to_status` parameter.
See [Errors Handling](../errors/). +| **Handle errors** | Map the exceptions to HTTP statuses in the `fos_rest.exception` parameter.
See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst). | Map the exceptions to HTTP statuses in the `api_platform.exception_to_status` parameter.
See [Errors Handling](../errors/). | **Security** | Use Symfony's security features directly with the `security.yaml` in your controller or the `security.yml` file. | Use the `security` attribute in the `ApiResource` and `ApiProperty` attributes. It is an [Expression language](https://symfony.com/doc/current/components/expression_language/) string describing who can access your resources, and the properties of your resources. By default, everything is accessible without authentication.
Note you can also use the `security.yml` file if you don't need so specific rules.
See [Security](../security/). | **API versioning** | FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use.
See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst). | API Platform has no native support to API versioning, but instead provide an approach consisting of deprecating resources when needed. This allows a smoother upgrade for clients, as they need to change their code only when it is necessary.
See [Deprecating Resources and Properties](../deprecations/). From 5c6fea5c43b1fcf90d845c65539302405c4dc0f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tanghe?= Date: Wed, 3 Nov 2021 11:40:48 +0100 Subject: [PATCH 3/9] Fix reviews --- core/migration-guides/fosrestbundle.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/core/migration-guides/fosrestbundle.md b/core/migration-guides/fosrestbundle.md index 4d005aa863e..9d049ff6b40 100644 --- a/core/migration-guides/fosrestbundle.md +++ b/core/migration-guides/fosrestbundle.md @@ -10,12 +10,12 @@ The table below provides a list of the main features you can find in FOSRestBund | Feature | FOSRestBundle | API Platform | --- | --- | --- -| **Make CRUD endpoints** | 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). | Add the `ApiResource` attribute to your entities, and enable operations you desire inside. By default, every operations are activated.
See [Operations](../operations/). -| **Make custom controllers** | Same as above. | Create an invokable class, do your magic inside, and declare it in your entity's `ApiResource`.
See [Creating Custom Operations and Controllers](../controllers/). -| **Routing system** (with native documentation support) | Annotate your controllers with FOSRest's route annotations that are the most suitable to your needs.
See [Full default annotations](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst). | This is handled by the `ApiResource` attribute mentionned above. -| **Hook into the requests handling** | 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). | Listen to Symfony's events to modify the HTTP responses. API Platform provides a lot of constants to help you set priorities correctly.
See [The Event System](../events/). -| **Customize the formats of the requests and the responses** | Only the request body's format can be customized.
Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML.
See [Body Listener](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and the response body's format can be customized.
You can configure the formats of the API either globally or in specific resources or operations. API Platform provides native support for multiple formats including JSON, XML, CSV, YAML, etc.
See [Content negociation](../content-negotiation/). -| **Name conversion** | Only the request bodys can be converted before entering into your controller.
FOSRest provides two native normalizers for converting the names of your JSON keys to camelCase. You can create your own ones by implementing the `ArrayNormalizerInterface`.
See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and response bodys can be converted.
API Platform uses the name converters included in the Serializer compononent of Symfony. You can create your own by implementing the `NameConverterInterface` provided by Symfony.
See [_Name Conversion_ in The Serialization Process](../serialization/#name-conversion). -| **Handle errors** | Map the exceptions to HTTP statuses in the `fos_rest.exception` parameter.
See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst). | Map the exceptions to HTTP statuses in the `api_platform.exception_to_status` parameter.
See [Errors Handling](../errors/). -| **Security** | Use Symfony's security features directly with the `security.yaml` in your controller or the `security.yml` file. | Use the `security` attribute in the `ApiResource` and `ApiProperty` attributes. It is an [Expression language](https://symfony.com/doc/current/components/expression_language/) string describing who can access your resources, and the properties of your resources. By default, everything is accessible without authentication.
Note you can also use the `security.yml` file if you don't need so specific rules.
See [Security](../security/). -| **API versioning** | FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use.
See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst). | API Platform has no native support to API versioning, but instead provide an approach consisting of deprecating resources when needed. This allows a smoother upgrade for clients, as they need to change their code only when it is necessary.
See [Deprecating Resources and Properties](../deprecations/). +| **Make CRUD endpoints** | 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). | Add the `ApiResource` attribute to your entities, and enable operations you desire inside. By default, every operations are activated.
See [Operations](../operations.md). +| **Make custom controllers** | 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.
See [General Design Considerations](../design.md). +| **Routing system** (with native documentation support) | Annotate your controllers with FOSRest's route annotations that are the most suitable to your needs.
See [Full default annotations](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst). | Use the `ApiResource` attribute to activate the HTTP methods you need for your entity. By default, all the methods are enabled.
See [Operations](../operations.md). +| **Hook into the requests handling** | 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). | API Platform provides a lot of ways to customize the behavior of your API, depending on what you exactly want to do.
See [Extending API Platform](../extending.md) for more details. +| **Customize the formats of the requests and the responses** | Only the request body's format can be customized.
Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML.
See [Body Listener](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and the response body's format can be customized.
You can configure the formats of the API either globally or in specific resources or operations. API Platform provides native support for multiple formats including JSON, XML, CSV, YAML, etc.
See [Content negociation](../content-negotiation.md). +| **Name conversion** | Only the request bodys can be converted before entering into your controller.
FOSRest provides two native normalizers for converting the names of your JSON keys to camelCase. You can create your own ones by implementing the `ArrayNormalizerInterface`.
See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and response bodys can be converted.
API Platform uses the [name converters](https://symfony.com/doc/current/components/serializer.html#component-serializer-converting-property-names-when-serializing-and-deserializing) included in the Serializer component of Symfony. You can create your own by implementing the `NameConverterInterface` provided by Symfony.
See [_Name Conversion_ in The Serialization Process](../serialization.md#name-conversion). +| **Handle errors** | Map the exceptions to HTTP statuses in the `fos_rest.exception` parameter.
See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst). | Map the exceptions to HTTP statuses in the `api_platform.exception_to_status` parameter.
See [Errors Handling](../errors.md). +| **Security** | Use Symfony's security features directly with the `security.yaml` in your controller or the `security.yml` file. | Use the `security` attribute in the `ApiResource` and `ApiProperty` attributes. It is an [Expression language](https://symfony.com/doc/current/components/expression_language.md) string describing who can access your resources, and the properties of your resources. By default, everything is accessible without authentication.
Note you can also use the `security.yml` file if you only need to limit access to specific roles.
See [Security](../security.md). +| **API versioning** | FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use.
See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst). | API Platform has no native support to API versioning, but instead provide an approach consisting of deprecating resources when needed. This 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). From 9a61717d74949b87a3d9b850b51ec556c661b2a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tanghe?= Date: Wed, 3 Nov 2021 15:05:48 +0100 Subject: [PATCH 4/9] Fix reviews --- core/migration-guides.md | 5 +++++ core/migration-guides/fosrestbundle.md | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 core/migration-guides.md diff --git a/core/migration-guides.md b/core/migration-guides.md new file mode 100644 index 00000000000..37e80bdcadb --- /dev/null +++ b/core/migration-guides.md @@ -0,0 +1,5 @@ +# Migration guides + +This section contains guides to help you migrating from another API solution to API Platform. + +- [Migrate from FOSRestBundle](migration-guides/fosrestbundle.md) diff --git a/core/migration-guides/fosrestbundle.md b/core/migration-guides/fosrestbundle.md index 9d049ff6b40..92ea91abf96 100644 --- a/core/migration-guides/fosrestbundle.md +++ b/core/migration-guides/fosrestbundle.md @@ -15,7 +15,7 @@ The table below provides a list of the main features you can find in FOSRestBund | **Routing system** (with native documentation support) | Annotate your controllers with FOSRest's route annotations that are the most suitable to your needs.
See [Full default annotations](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst). | Use the `ApiResource` attribute to activate the HTTP methods you need for your entity. By default, all the methods are enabled.
See [Operations](../operations.md). | **Hook into the requests handling** | 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). | API Platform provides a lot of ways to customize the behavior of your API, depending on what you exactly want to do.
See [Extending API Platform](../extending.md) for more details. | **Customize the formats of the requests and the responses** | Only the request body's format can be customized.
Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML.
See [Body Listener](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and the response body's format can be customized.
You can configure the formats of the API either globally or in specific resources or operations. API Platform provides native support for multiple formats including JSON, XML, CSV, YAML, etc.
See [Content negociation](../content-negotiation.md). -| **Name conversion** | Only the request bodys can be converted before entering into your controller.
FOSRest provides two native normalizers for converting the names of your JSON keys to camelCase. You can create your own ones by implementing the `ArrayNormalizerInterface`.
See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and response bodys can be converted.
API Platform uses the [name converters](https://symfony.com/doc/current/components/serializer.html#component-serializer-converting-property-names-when-serializing-and-deserializing) included in the Serializer component of Symfony. You can create your own by implementing the `NameConverterInterface` provided by Symfony.
See [_Name Conversion_ in The Serialization Process](../serialization.md#name-conversion). +| **Name conversion** | Only request bodies can be converted before entering into your controller.
FOSRest provides two native normalizers for converting the names of your JSON keys to camelCase. You can create your own ones by implementing the `ArrayNormalizerInterface`.
See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both request and response bodies can be converted.
API Platform uses [name converters](https://symfony.com/doc/current/components/serializer.html#component-serializer-converting-property-names-when-serializing-and-deserializing) included in the Serializer component of Symfony. You can create your own by implementing the `NameConverterInterface` provided by Symfony.
See [_Name Conversion_ in The Serialization Process](../serialization.md#name-conversion). | **Handle errors** | Map the exceptions to HTTP statuses in the `fos_rest.exception` parameter.
See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst). | Map the exceptions to HTTP statuses in the `api_platform.exception_to_status` parameter.
See [Errors Handling](../errors.md). -| **Security** | Use Symfony's security features directly with the `security.yaml` in your controller or the `security.yml` file. | Use the `security` attribute in the `ApiResource` and `ApiProperty` attributes. It is an [Expression language](https://symfony.com/doc/current/components/expression_language.md) string describing who can access your resources, and the properties of your resources. By default, everything is accessible without authentication.
Note you can also use the `security.yml` file if you only need to limit access to specific roles.
See [Security](../security.md). +| **Security** | Use [Symfony's Security component](https://symfony.com/doc/current/security) to control your API access. | Use the `security` attribute in the `ApiResource` and `ApiProperty` attributes. It is an [Expression language](https://symfony.com/doc/current/components/expression_language.md) string describing who can access your resources or who can see the properties of your resources. By default, everything is accessible without authentication.
Note you can also use the `security.yml` file if you only need to limit access to specific roles.
See [Security](../security.md). | **API versioning** | FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use.
See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst). | API Platform has no native support to API versioning, but instead provide an approach consisting of deprecating resources when needed. This 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). From ece244b6ce33f4655391deaa08de19b31b47a8ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tanghe?= Date: Wed, 3 Nov 2021 15:25:29 +0100 Subject: [PATCH 5/9] Add migration guides to outline.yaml --- outline.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/outline.yaml b/outline.yaml index 1e34507f5ff..aa8b0588c6a 100644 --- a/outline.yaml +++ b/outline.yaml @@ -10,6 +10,7 @@ chapters: items: - index - getting-started + - migration-guides - design - extending - testing From 6bce6ca5c28716676c51e9b8603ea32458b024ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tanghe?= Date: Wed, 3 Nov 2021 15:27:02 +0100 Subject: [PATCH 6/9] Fix typos --- core/migration-guides/fosrestbundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/migration-guides/fosrestbundle.md b/core/migration-guides/fosrestbundle.md index 92ea91abf96..8893451a91a 100644 --- a/core/migration-guides/fosrestbundle.md +++ b/core/migration-guides/fosrestbundle.md @@ -18,4 +18,4 @@ The table below provides a list of the main features you can find in FOSRestBund | **Name conversion** | Only request bodies can be converted before entering into your controller.
FOSRest provides two native normalizers for converting the names of your JSON keys to camelCase. You can create your own ones by implementing the `ArrayNormalizerInterface`.
See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both request and response bodies can be converted.
API Platform uses [name converters](https://symfony.com/doc/current/components/serializer.html#component-serializer-converting-property-names-when-serializing-and-deserializing) included in the Serializer component of Symfony. You can create your own by implementing the `NameConverterInterface` provided by Symfony.
See [_Name Conversion_ in The Serialization Process](../serialization.md#name-conversion). | **Handle errors** | Map the exceptions to HTTP statuses in the `fos_rest.exception` parameter.
See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst). | Map the exceptions to HTTP statuses in the `api_platform.exception_to_status` parameter.
See [Errors Handling](../errors.md). | **Security** | Use [Symfony's Security component](https://symfony.com/doc/current/security) to control your API access. | Use the `security` attribute in the `ApiResource` and `ApiProperty` attributes. It is an [Expression language](https://symfony.com/doc/current/components/expression_language.md) string describing who can access your resources or who can see the properties of your resources. By default, everything is accessible without authentication.
Note you can also use the `security.yml` file if you only need to limit access to specific roles.
See [Security](../security.md). -| **API versioning** | FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use.
See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst). | API Platform has no native support to API versioning, but instead provide an approach consisting of deprecating resources when needed. This 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). +| **API versioning** | FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use.
See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst). | 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.
See [Deprecating Resources and Properties](../deprecations.md). From 2eeef372ed2b4c24e503b3846597c07bdada8513 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tanghe?= Date: Wed, 3 Nov 2021 16:13:43 +0100 Subject: [PATCH 7/9] Reformat the page, fix the menu --- core/migrate-from-fosrestbundle.md | 144 +++++++++++++++++++++++++ core/migration-guides.md | 5 - core/migration-guides/fosrestbundle.md | 21 ---- outline.yaml | 2 +- 4 files changed, 145 insertions(+), 27 deletions(-) create mode 100644 core/migrate-from-fosrestbundle.md delete mode 100644 core/migration-guides.md delete mode 100644 core/migration-guides/fosrestbundle.md diff --git a/core/migrate-from-fosrestbundle.md b/core/migrate-from-fosrestbundle.md new file mode 100644 index 00000000000..fd791e63e1e --- /dev/null +++ b/core/migrate-from-fosrestbundle.md @@ -0,0 +1,144 @@ +# Migrate From FOSRestBundle + +[FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle) is a popular bundle to rapidly develop RESTful APIs with Symfony. + +In September 2021, [it has been announced to be deprecated](https://twitter.com/lsmith/status/1440216817876627459) and its maintainers recommended to use API Platform instead. This page provides a guide to help developers migrating from FOSRestBundle to API Platform. + +## Features Comparison + +The table below provides a list of the main features you can find in FOSRestBundle 3.1, and their equivalents in API Platform. + +### Make CRUD endpoints + +**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`. + +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. + +See [Operations](../operations.md). + +### Make custom controllers + +**In FOSRestBundle** + +Same as above. + +**In API Platform** + +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. + +See [General Design Considerations](../design.md). + + +### Routing system (with native documentation support) + +**In FOSRestBundle** + +Annotate your controllers with FOSRest's route annotations that are the most suitable to your needs. + +See [Full default annotations](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst). + +**In API Platform** + +Use the `ApiResource` attribute to activate the HTTP methods you need for your entity. By default, all the methods are enabled. + +See [Operations](../operations.md). + +### Hook into the requests handling + +**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. + +See [Listener support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/3-listener-support.rst). + +**In API Platform** + +API Platform provides a lot of ways to customize the behavior of your API, depending on what you exactly want to do. + +See [Extending API Platform](../extending.md) for more details. + +### Customize the formats of the requests and the responses + +**In FOSRestBundle** + +Only the request body's format can be customized. + +Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML. + +See [Body Listener](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). + +**In API Platform** + +Both the request and the response body's format can be customized. + +You can configure the formats of the API either globally or in specific resources or operations. API Platform provides native support for multiple formats including JSON, XML, CSV, YAML, etc. + +See [Content negociation](../content-negotiation.md). + +### Name conversion + +**In FOSRestBundle** + +Only request bodies can be converted before entering into your controller. + +FOSRest provides two native normalizers for converting the names of your JSON keys to camelCase. You can create your own ones by implementing the `ArrayNormalizerInterface`. + +See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). + +**In API Platform** + +Both request and response bodies can be converted. + +API Platform uses [name converters](https://symfony.com/doc/current/components/serializer.html#component-serializer-converting-property-names-when-serializing-and-deserializing) included in the Serializer component of Symfony. You can create your own by implementing the `NameConverterInterface` provided by Symfony. + +See [_Name Conversion_ in The Serialization Process](../serialization.md#name-conversion). + +### Handle errors + +**In FOSRestBundle** + +Map the exceptions to HTTP statuses in the `fos_rest.exception` parameter. + +See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst). + +**In API Platform** + +Map the exceptions to HTTP statuses in the `api_platform.exception_to_status` parameter. + +See [Errors Handling](../errors.md). + +### Security + +**In FOSRestBundle** + +Use [Symfony's Security component](https://symfony.com/doc/current/security) to control your API access. + +**In API Platform** + +Use the `security` attribute in the `ApiResource` and `ApiProperty` attributes. It is an [Expression language](https://symfony.com/doc/current/components/expression_language.md) string describing who can access your resources or who can see the properties of your resources. By default, everything is accessible without authentication. + +Note you can also use the `security.yml` file if you only need to limit access to specific roles. + +See [Security](../security.md). + +### API versioning + +**In FOSRestBundle** + +FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use. + +See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst). + +**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. + +See [Deprecating Resources and Properties](../deprecations.md). diff --git a/core/migration-guides.md b/core/migration-guides.md deleted file mode 100644 index 37e80bdcadb..00000000000 --- a/core/migration-guides.md +++ /dev/null @@ -1,5 +0,0 @@ -# Migration guides - -This section contains guides to help you migrating from another API solution to API Platform. - -- [Migrate from FOSRestBundle](migration-guides/fosrestbundle.md) diff --git a/core/migration-guides/fosrestbundle.md b/core/migration-guides/fosrestbundle.md deleted file mode 100644 index 8893451a91a..00000000000 --- a/core/migration-guides/fosrestbundle.md +++ /dev/null @@ -1,21 +0,0 @@ -# Migrate From FOSRestBundle - -[FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle) is a popular bundle to rapidly develop RESTful APIs with Symfony. - -In September 2021, [it has been announced to be deprecated](https://twitter.com/lsmith/status/1440216817876627459) and its maintainers recommended to use API Platform instead. This page provides a guide to help developers migrating from FOSRestBundle to API Platform. - -## Features Comparison - -The table below provides a list of the main features you can find in FOSRestBundle 3.1, and their equivalents in API Platform. - -| Feature | FOSRestBundle | API Platform -| --- | --- | --- -| **Make CRUD endpoints** | 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). | Add the `ApiResource` attribute to your entities, and enable operations you desire inside. By default, every operations are activated.
See [Operations](../operations.md). -| **Make custom controllers** | 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.
See [General Design Considerations](../design.md). -| **Routing system** (with native documentation support) | Annotate your controllers with FOSRest's route annotations that are the most suitable to your needs.
See [Full default annotations](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst). | Use the `ApiResource` attribute to activate the HTTP methods you need for your entity. By default, all the methods are enabled.
See [Operations](../operations.md). -| **Hook into the requests handling** | 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). | API Platform provides a lot of ways to customize the behavior of your API, depending on what you exactly want to do.
See [Extending API Platform](../extending.md) for more details. -| **Customize the formats of the requests and the responses** | Only the request body's format can be customized.
Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML.
See [Body Listener](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both the request and the response body's format can be customized.
You can configure the formats of the API either globally or in specific resources or operations. API Platform provides native support for multiple formats including JSON, XML, CSV, YAML, etc.
See [Content negociation](../content-negotiation.md). -| **Name conversion** | Only request bodies can be converted before entering into your controller.
FOSRest provides two native normalizers for converting the names of your JSON keys to camelCase. You can create your own ones by implementing the `ArrayNormalizerInterface`.
See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst). | Both request and response bodies can be converted.
API Platform uses [name converters](https://symfony.com/doc/current/components/serializer.html#component-serializer-converting-property-names-when-serializing-and-deserializing) included in the Serializer component of Symfony. You can create your own by implementing the `NameConverterInterface` provided by Symfony.
See [_Name Conversion_ in The Serialization Process](../serialization.md#name-conversion). -| **Handle errors** | Map the exceptions to HTTP statuses in the `fos_rest.exception` parameter.
See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst). | Map the exceptions to HTTP statuses in the `api_platform.exception_to_status` parameter.
See [Errors Handling](../errors.md). -| **Security** | Use [Symfony's Security component](https://symfony.com/doc/current/security) to control your API access. | Use the `security` attribute in the `ApiResource` and `ApiProperty` attributes. It is an [Expression language](https://symfony.com/doc/current/components/expression_language.md) string describing who can access your resources or who can see the properties of your resources. By default, everything is accessible without authentication.
Note you can also use the `security.yml` file if you only need to limit access to specific roles.
See [Security](../security.md). -| **API versioning** | FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use.
See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst). | 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.
See [Deprecating Resources and Properties](../deprecations.md). diff --git a/outline.yaml b/outline.yaml index aa8b0588c6a..f82cdd9c3ab 100644 --- a/outline.yaml +++ b/outline.yaml @@ -10,7 +10,7 @@ chapters: items: - index - getting-started - - migration-guides + - migrate-from-fosrestbundle - design - extending - testing From 041b47bdeb95d3f283e6354d389900030668bc3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tanghe?= Date: Wed, 3 Nov 2021 16:30:23 +0100 Subject: [PATCH 8/9] Remove paragraph about FOSRest's deprecation --- core/migrate-from-fosrestbundle.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/core/migrate-from-fosrestbundle.md b/core/migrate-from-fosrestbundle.md index fd791e63e1e..a567e52010c 100644 --- a/core/migrate-from-fosrestbundle.md +++ b/core/migrate-from-fosrestbundle.md @@ -1,8 +1,7 @@ # Migrate From FOSRestBundle [FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle) is a popular bundle to rapidly develop RESTful APIs with Symfony. - -In September 2021, [it has been announced to be deprecated](https://twitter.com/lsmith/status/1440216817876627459) and its maintainers recommended to use API Platform instead. This page provides a guide to help developers migrating from FOSRestBundle to API Platform. +This page provides a guide to help developers migrating from FOSRestBundle to API Platform. ## Features Comparison From 627231911d3c125af93fb04c9fe2b94e185ce28d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tanghe?= Date: Thu, 4 Nov 2021 10:33:07 +0100 Subject: [PATCH 9/9] Adding links to the page, moving the new section below Configuration --- core/getting-started.md | 4 ++++ core/migrate-from-fosrestbundle.md | 2 ++ extra/troubleshooting.md | 2 ++ outline.yaml | 2 +- 4 files changed, 9 insertions(+), 1 deletion(-) diff --git a/core/getting-started.md b/core/getting-started.md index 3aeb41ab242..a92863c4fc7 100644 --- a/core/getting-started.md +++ b/core/getting-started.md @@ -1,5 +1,9 @@ # Getting started +## Migrating from FOSRestBundle + +If you plan to migrate from FOSRestBundle, you might want to read [this guide](migrate-from-fosrestbundle.md) to get started with API Platform. + ## Installing API Platform Core If you are starting a new project, the easiest way to get API Platform up is to install the [API Platform Distribution](../distribution/index.md). diff --git a/core/migrate-from-fosrestbundle.md b/core/migrate-from-fosrestbundle.md index a567e52010c..6b0c05462e3 100644 --- a/core/migrate-from-fosrestbundle.md +++ b/core/migrate-from-fosrestbundle.md @@ -3,6 +3,8 @@ [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. +[On 21 September, 2021](https://twitter.com/lsmith/status/1440216817876627459), FOSRestBundle's creators recommended to use API Platform. + ## Features Comparison The table below provides a list of the main features you can find in FOSRestBundle 3.1, and their equivalents in API Platform. diff --git a/extra/troubleshooting.md b/extra/troubleshooting.md index 104a40bec51..575dffee4ae 100644 --- a/extra/troubleshooting.md +++ b/extra/troubleshooting.md @@ -42,6 +42,8 @@ jms_serializer: The JMS Serializer service is available as `jms_serializer`. +**Note:** if you are using JMSSerializerBundle along with FOSRestBundle and considering migrating to API Platform, you might want to take a look at [this guide](migrate-from-fosrestbundle.md) too. + ## "upstream sent too big header while reading response header from upstream" NGINX 502 Error Some of your API calls fail with a 502 error and the logs for the api container shows the following error message `upstream sent too big header while reading response header from upstream`. diff --git a/outline.yaml b/outline.yaml index f82cdd9c3ab..81fb5eff228 100644 --- a/outline.yaml +++ b/outline.yaml @@ -10,7 +10,6 @@ chapters: items: - index - getting-started - - migrate-from-fosrestbundle - design - extending - testing @@ -53,6 +52,7 @@ chapters: - nelmio-api-doc - bootstrap - configuration + - migrate-from-fosrestbundle - title: The Schema Generator Component path: schema-generator items: