Skip to content

Commit 541291e

Browse files
Deuchnordalanpoulain
Deuchnord
and
alanpoulain
authored
docs: add guide to migrate from FOSRestBundle (#1460)
* docs: add guide to migrate from FOSRestBundle * Fix typos Co-authored-by: Alan Poulain <contact@alanpoulain.eu> * Fix reviews * Fix reviews * Add migration guides to outline.yaml * Fix typos * Reformat the page, fix the menu * Remove paragraph about FOSRest's deprecation * Adding links to the page, moving the new section below Configuration Co-authored-by: Alan Poulain <contact@alanpoulain.eu>
1 parent 71b02e1 commit 541291e

File tree

4 files changed

+152
-0
lines changed

4 files changed

+152
-0
lines changed

‎core/getting-started.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Getting started
22

3+
## Migrating from FOSRestBundle
4+
5+
If you plan to migrate from FOSRestBundle, you might want to read [this guide](migrate-from-fosrestbundle.md) to get started with API Platform.
6+
37
## Installing API Platform Core
48

59
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).

‎core/migrate-from-fosrestbundle.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Migrate From FOSRestBundle
2+
3+
[FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle) is a popular bundle to rapidly develop RESTful APIs with Symfony.
4+
This page provides a guide to help developers migrating from FOSRestBundle to API Platform.
5+
6+
[On 21 September, 2021](https://twitter.com/lsmith/status/1440216817876627459), FOSRestBundle's creators recommended to use API Platform.
7+
8+
## Features Comparison
9+
10+
The table below provides a list of the main features you can find in FOSRestBundle 3.1, and their equivalents in API Platform.
11+
12+
### Make CRUD endpoints
13+
14+
**In FOSRestBundle**
15+
16+
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`.
17+
18+
See [The view layer](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/2-the-view-layer.rst).
19+
20+
**In API Platform**
21+
22+
Add the `ApiResource` attribute to your entities, and enable operations you desire inside. By default, every operations are activated.
23+
24+
See [Operations](../operations.md).
25+
26+
### Make custom controllers
27+
28+
**In FOSRestBundle**
29+
30+
Same as above.
31+
32+
**In API Platform**
33+
34+
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.
35+
36+
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.
37+
38+
See [General Design Considerations](../design.md).
39+
40+
41+
### Routing system (with native documentation support)
42+
43+
**In FOSRestBundle**
44+
45+
Annotate your controllers with FOSRest's route annotations that are the most suitable to your needs.
46+
47+
See [Full default annotations](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst).
48+
49+
**In API Platform**
50+
51+
Use the `ApiResource` attribute to activate the HTTP methods you need for your entity. By default, all the methods are enabled.
52+
53+
See [Operations](../operations.md).
54+
55+
### Hook into the requests handling
56+
57+
**In FOSRestBundle**
58+
59+
Listen to FOSRest's events to modify the requests before they come into your controllers, and the responses after they come out of them.
60+
61+
See [Listener support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/3-listener-support.rst).
62+
63+
**In API Platform**
64+
65+
API Platform provides a lot of ways to customize the behavior of your API, depending on what you exactly want to do.
66+
67+
See [Extending API Platform](../extending.md) for more details.
68+
69+
### Customize the formats of the requests and the responses
70+
71+
**In FOSRestBundle**
72+
73+
Only the request body's format can be customized.
74+
75+
Use body listeners to use either FOSRest's own decoders or your own ones. FOSRestBundle provides native support for JSON and XML.
76+
77+
See [Body Listener](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst).
78+
79+
**In API Platform**
80+
81+
Both the request and the response body's format can be customized.
82+
83+
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.
84+
85+
See [Content negociation](../content-negotiation.md).
86+
87+
### Name conversion
88+
89+
**In FOSRestBundle**
90+
91+
Only request bodies can be converted before entering into your controller.
92+
93+
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`.
94+
95+
See [Body Listeners](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/body_listener.rst).
96+
97+
**In API Platform**
98+
99+
Both request and response bodies can be converted.
100+
101+
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.
102+
103+
See [_Name Conversion_ in The Serialization Process](../serialization.md#name-conversion).
104+
105+
### Handle errors
106+
107+
**In FOSRestBundle**
108+
109+
Map the exceptions to HTTP statuses in the `fos_rest.exception` parameter.
110+
111+
See [ExceptionController support](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/4-exception-controller-support.rst).
112+
113+
**In API Platform**
114+
115+
Map the exceptions to HTTP statuses in the `api_platform.exception_to_status` parameter.
116+
117+
See [Errors Handling](../errors.md).
118+
119+
### Security
120+
121+
**In FOSRestBundle**
122+
123+
Use [Symfony's Security component](https://symfony.com/doc/current/security) to control your API access.
124+
125+
**In API Platform**
126+
127+
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.
128+
129+
Note you can also use the `security.yml` file if you only need to limit access to specific roles.
130+
131+
See [Security](../security.md).
132+
133+
### API versioning
134+
135+
**In FOSRestBundle**
136+
137+
FOSRestBundle provides a way to provide versions to your APIs in a way users have to specify which one they want to use.
138+
139+
See [API versioning](https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/versioning.rst).
140+
141+
**In API Platform**
142+
143+
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.
144+
145+
See [Deprecating Resources and Properties](../deprecations.md).

‎extra/troubleshooting.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ jms_serializer:
4242
4343
The JMS Serializer service is available as `jms_serializer`.
4444

45+
**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.
46+
4547
## "upstream sent too big header while reading response header from upstream" NGINX 502 Error
4648

4749
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`.

‎outline.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ chapters:
5252
- nelmio-api-doc
5353
- bootstrap
5454
- configuration
55+
- migrate-from-fosrestbundle
5556
- title: The Schema Generator Component
5657
path: schema-generator
5758
items:

0 commit comments

Comments
 (0)