A Quick API Platform Hands On Review for Symfony App Development
There are many ways of REST API implementation in a Symfony app. One of them is the REST API Platform. Let's review an API platform for Symfony app development.
Join the DZone community and get the full member experience.Join For Free
There are many ways of REST API implementation in a Symfony app. One of them is the REST API Platform. We get REST API protocol support, documentation, and Swagger UI with the possibility to test endpoints out of the box.
We add an API platform into the application.
Swagger UI is active by default and available at http://localhost/api
While no endpoint is defined (the operation in API Platform terms), it’s simple to do it. You should only add annotation @ApiResource to the entity.
- Collection operations— operations with the collection of elements
- Item operations— operations with a data element
- GET: to get a list of elements
- POST: to add an element to the collection
- GET: to get an element by ID
- PUT: to change an element
- DELETE: to delete an element from the collection
- PATCH: to partly substitute the element
Element configuration can be described in the annotations, xml, or yaml files. The yaml files location is defined by the path parameter of the configuration file
If it’s needed, we can restrict the set of the operations with a list:
or in a yaml file:
The elements collections support a per-page layout.
If it is necessary to check the input data, it is enough to add an entity property validator — the API platform generates an error message:
with a line of more than 50 characters we’ll get an error:
To provide the uniqueness of object identifiers API platform uses IRI (Internationalized Resource Identifier). Each object’s IRI coincides with the GET request for this object
/api/customer/123. The same type of identifier is used for the requests of objects adding and editing.
Let’s add a new entity related to the Customer entity.
The body of the request to add a new item will look like this:
The list of the collection items will look like this:
As you can see, the list of messages is presented as an array of IRI strings:
http: // localhost / api / messages / 1 will provide such result:
Using serialization groups, we can display not only the IRI of the object but also the data of the nested object in case of necessity. To do this, for the item operation GET, we’ll specify the serialization group:
We’ll add the group to the properties of the Message and Customer objects. Now the result of the same query will be different.
API platform has a built-in filter mechanism:
Doctrine ORM and Mongo ODM
- Search filter (string fields)
- Date filter
- Boolean filter
- Range filter (numeric fields)
- Exists filter (nullable values)
- Order filter (collection’s sort order changes)
- Ordering filter
- Matching filter
- Term filter
- Group filter (defines a list of serialization groups for the query result)
- Property filter (defines the list of displayed properties)
There is also a possibility to define the user filter types. Let’s add the string fields filter for example:
We have added 2 filters
- by title field—it will search for all the elements, which have the title field ending as in the search sample. The search is case-independent (symbol
iat the beginning of the filter type name).
- by text field—will search for all the elements having a search sample in the text field. The search depends on the case.
Data Transfer Objects (DTO) Usage
In case of necessity we can use not the entities directly, but DTOs. We have to take 3 steps for this.
- To describe DTOs input and output classes.
- Indicate the classes as input and output in our entity parameters.
- Describe Data Transformer classes for entity into DTO transformation and back.
Adding DTO classes into entity description
Data Transformer for input DTO
Data Transformer for output DTO
Such an approach has a drawback – DTO validation won’t work. To correct this, you should change the transformer class input DTO.
In case none of the methods described above allows us to get the desirable result, we have an opportunity to use our own controller.
The name of the method parameter
is __invoke, there should obligatory be
$data. Otherwise, it would be empty. Let’s add the controller into the entity configuration.
And we add the controller class:
User Data Sources
Data access with Doctrine ORM and Elasticsearch-PHP are built-in as standard in the API Platform. Doctrine ORM is active immediately after installation; Elasticsearch-PHP can be switched on in the configuration file.
For the other data sources options, we can define our own data source by adding a new class. We should implement the CollectionDataProviderInterface, RestrictedDataProviderInterface interfaces for the collection provider or ItemDataProviderInterface, RestrictedDataProviderInterface for the collection item provider. Another provider is involved in data modification; it implements the ContextAwareDataPersisterInterface interface.
Impressions and Findings
API Platform is much more extensive than it was revealed in this review. We did not mention here the automated generation of documentation and JSON schemes, serialization management, security and access control, platform own extensions, integration with Symfony Messenger, and other features. A full description can be found in the official documentation at https://api-platform.com/docs/. The purpose of this article was the hands-on review of the tool.
API Platform includes a large toolkit for writing a REST API which will allow you to implement most of the tasks that arise during the REST API Backend by writing with a minimum amount of code. At the same time all the actions, which are beyond CRUD, should be realized independently in the form of standard controllers.
Published at DZone with permission of Oleksandra Liubytska. See the original article here.
Opinions expressed by DZone contributors are their own.