docs: add guide to migrate from FOSRestBundle

Author: Deuchnord

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`.<br />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.<br />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`.<br />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.<br />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.<br />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.<br />See [The Event System](../events/).
+| **Customize the formats of the requests and the responses** | Only the request body's format can be customized.<br />Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML.<br />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.<br />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.<br />See [Content negociation](../content-negotiation/).
+| **Name conversion** | Only the request bodys can be converted before entering into your controller.<br />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`.<br />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.<br />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.<br />See [_Name Conversion_ in The Serialization Process](../serialization/#name-conversion).
+| **Handle errors** | Map the exeptions to HTTP statuses in the `fos_rest.exception` parameter.<br />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.<br />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.<br />Note you can also use the `security.yml` file if you don't need so specific rules.<br />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.<br />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.<br />See [Deprecating Resources and Properties](../deprecations/).