Practical guide to API Platform: How to tell if it’s the right framework for you

OK, what’s the API Platform?

API Platform was created in 2015 by a Symfony expert, Kévin Dunglas. It was claimed to be one of the most important development events on SymfonyCon in Paris, alongside Platform.sh and Blackfire.io. Among those three, I think the API Platform was the most successful one. While the first version had indeed some annoying mechanisms, the framework was greatly enhanced in version 2. But let’s start from the beginning: what does it actually do?

In short, API Platform is a tool based on the PHP Symfony framework which helps you speed up building the backend part of your project.

Especially at the beginning of the development process (but sometimes in later stages as well), we have to put the same code over and over again without any or with some little changes, for example when implementing the paging mechanism or an authorization system. It doesn’t matter if you’re creating an app for a bookshop or for a car renting company – for sure there’ll be a list of some items, a place where you can add an item, edit it and, of course, delete it.

Mechanisms that allow you to speed up the development of those parts are called CRUD or boilerplate. And there are lots of them on the market. You’ve probably already used Admin Generator for Symfony 1 or Scaffolding for Ruby on Rails. What’s new in API Platform is that times have changed and now we’re facing a completely different approach to architecture. All the previous solutions were creating monolith codes where the backend and frontend were created on the server-side. Now, we tend to implement more service-oriented architecture with a backend API that serves the data and a couple of clients consuming it – for example frontend SPA applications or mobile apps. API Platform focuses only on API, leaving the presentation layer to others.

What benefits will the API Platform bring me from the beginning?

Here’s the list of my favorites:

• A ready-to-use API based on REST with a variety of formats to choose from – JSON, XML, CSV, whatever you need. You can also change the format with one simple alteration in a configuration file. All methods serve POST, PUT, GET and DELETE options.
• The API is built securely on the best programming practices, using one of the most popular PHP frameworks now – Symfony.
• It’s already optimized and shipped with a caching mechanism (Varnish).
• There’s automatically-generated documentation (we all know how much developers hate to write any docs, leave alone support them in the long term). Plus a fancy mini-console to run simple queries and play around with the examples.
• You don’t have to worry about things like filters, paging mechanisms, or error messages. This stuff can be enabled with just a few lines of code.

If I was about to present an estimation for building from scratch an API that, for example, handles about 3 database entities (let’s say, we have a school with classes, teachers, and students and need to build a really simple CRM) with some authorization, filters, paging and documentation, I’d say it’d took about 2-3 weeks to implement. With API Platform we can prepare it in one day.

You’re probably thinking…

RAD is only good at the beginning but when you go deeper, problems start. Isn’t it the same here?

Yes – that’s also true in this situation. After the basic setup, things tend to be a little more complicated than in the tutorial on the API Platform’s website (BTW: a very good tutorial). After you create a database as you like and configure all the relations, you’ll probably need some custom fields or some custom business logic for your API. You start to look for the code and it occurs that there isn’t any! You have to do everything via the special filters or create customized controllers. And both solutions require a pretty good knowledge of Symfony – the framework on which everything’s built here (I’ll get back to it later).

Is this for basic projects or rather for advanced ones?

Actually, it’s for both – the main problem is the gap in between. If you’re a beginner and just want to create a very simple API, you can for sure use this tool but please do not expect that you’ll be able to customize it exactly as you wish. I’ve also seen frontend developers who wanted to specialize their app on the frontend side using one of the modern SPA frameworks (like Angular or React for example) but still needed a simple API that’ll deliver them some backend data – API Platform worked very well for them.

The same situation is with mobile apps. I know that right now there are similar solutions just delivering you simple backend service in the cloud, like Firebase, but for me, it’s still easier and faster to run API Platform on my server than to configure it all using some cloud panel. It also gives me more flexibility. If you just follow the tutorial and change the sample database names to your own, you should really get your app within one day tops. It’s also available as a Docker container, but my advice is to not use it if you haven’t had anything in common with Docker before – you’ll just get frustrated at the beginning and lose lots of precious time and nerves. Installing it via composer (the second installation method in the tutorial) is, in my opinion, way more intuitive.

But what if I want to create a more complicated app?

Yes, you can create almost everything you want. But only under one condition – before you begin, you have to really know Symfony first. This is the biggest advantage and the biggest flaw of this solution – it’s all standing on top of another framework. Furthermore, as I’ve mentioned above, API Platform isn’t generating a CRUD code that you can just modify as you wish. I’ve used such code-generating solutions and they were very good at the beginning (you can just get some code and modify it easily without reading any further instructions) but there were certain issues with that:

• If you’re not an experienced developer, it becomes very messy soon. Sometimes even despite following very good programming practices.
• After modifying any part of the pre-generated code, there’s no turning back. You cannot generate it again for some database changes. There are some solutions that allow that but you need to cope with pretty confusing overriding mechanisms.

API Platform isn’t generating any code ­–­­­ it creates the content “on the fly”. It’s not really a new solution, as I remember similar tools being available years ago (even API Platform’s predecessor, Admin Panel from Symfony 1) but the problem with these older mechanisms was that usually, you had very low flexibility on what you could create – limited to what the author allowed you to do. Here the things are a little different, as API Platform is built following the “Symfony way” of how things should work, meaning it’s based on event-driven mechanisms.

How proficiently should I know Symfony before using the API Platform?

As I wrote above, if you really need to do advanced things in the API Platform, you need to know Symfony first. If you’ve created a couple of Symfony-based apps before and you love it, API Platform will be a perfect enhancement for you. If not, you should first focus on understanding how Symfony works. Here are the three most important things to learn:

• EventStack – That’s basically the first and most important part of Symfony you really need to get to know. You can find the documentation here. The only way you can modify anything within the API is if you hook into one of the events. To do it properly and avoid situations when you’re asking yourself “Why this @#$ isn’t doing what it’s supposed to do?”, you really need to know how events are working in Symfony and which events API Platform is using.
• Serializer – All the data that are transferred via API goes through a serialization component built-in Symfony. You can find the documentation here. If you’re wondering why the given field or structure isn’t displayed in the GET method, the issue probably lies in the serialization.
• Dependency Injection – You may have met this pattern in other modern frameworks. The general idea is that all the things should be independent of each other and then just bonded together at the final stage by “injecting one to another” – it improves the sustainability of the code and is a must-have in modern apps right now. Here’s the description of how Symfony handles that. As you might suspect, the API Platform is also injecting its code to other services and can also benefit from services that you wish to inject.

There’s also one more thing that some PHP developers might not be familiar with – annotations. Annotations first started to be a popular solution in Java and soon migrated to other platforms, including PHP. The basic concept is that you define how the class or method should behave by commenting on it in a proper way on top of it. Some frameworks use annotations so much, that in many cases the comment before the method name contains more data and instructions than the code itself – API Platform is definitely one of them. I call such an approach “annotation programming”. It can be very useful and descriptive but if you haven’t been familiar with such things before, you’ll need to get used to it now. Here’s a link for further reading. Of course, you can still use XML or YAML but I strongly recommend getting to know annotations, as it seems that they’re the future of programming.

This is a pretty big threshold to cross. Is it worth it?

If you know Symfony very well, along with API Platform you have a very powerful tool in hand. Creating APIs will be much more simple and cost-effective, everything based on a foundation of a very solid framework which is Symfony. But what if you’re not so familiar with the solutions I’ve mentioned above? Learning all of this stuff requires a lot of time and practice. In return, you just receive an ability to speed up the process of creating the most common element of the API.

However, in my opinion, it’s worth it. You’ll have to learn most of those components anyway if you’re planning to create a long-term project – if not in this framework, they’ll still appear in others. Although at first, this solution might be very hard to implement (you might be frustrated that the things aren’t working as you expected), there’s a good reason why it works this way, as it prevents developers from making a mess in the code which was one of the biggest problems in PHP some time ago.

It seems like you’re defending the API Platform. Does it have any flaws?

Like all frameworks, the API Platform also has some annoying issues that you just have to cope with. For me, the most important one is that you often cannot directly find help for the issue you’re dealing with on the internet. If you just type “API Platform <the problem you have>” in Google, you probably won’t find any solution and might be under impression that the community is very small.

That’s because 90% of questions regarding API Platform are in fact questions about Symfony itself.

Those questions are answered by the Symfony community – which, lucky for us, is a pretty big one. Therefore, in order to find your answer, you should rather search Symfony forums than the API Platform ones. This, of course, means that you have to ask the right questions and (again) know Symfony quite well. You can also get help by asking on GitHub – very often from Kévin Dunglas (the creator of API Platform) himself.

The second thing is the naming convention. Like any other CRUD solution, the API Platform has to generate some names of classes and methods on its own. Usually, those names reflect the names used in the database but you still have to guess how the particular method or filter has been named. For example, when working with the API Platform in The Software House, we had a table named “Language Spoken” and we got a method for retrieving all languages that users speak. There was a lot of confusion about the auto-generated name: will it be “getLanguagesSpoken” or “getLanguageSpokens” or maybe something else? We finally got a debugger tool from Symfony (which I also suggest you should do) to see the call stack and found out what the generated name was in fact.

Like other CRUD solutions which I’ve seen on the market, API Platform also has issues with virtual fields. Basically, the concept of such automated tools is that we have some database and that’s the main source of all the data and structure. However, sometimes we need to return values that are not directly stored in the database but just calculated based on some business logic (or, for example, fetched from some 3rd party source). In these cases, you can still add such fields to the API but they won’t be 100% supported and you may expect some issues with that. For example, sorting is by default executed as the database query, so for a virtual field, you cannot add sorting easily (even if you implement some functions providing sorting rules).

It’s also worth mentioning that although you can use any output provided by API Platform in your other Symfony bundles, it is very complicated to make API Platform use any other bundles and make API out of them. For example, if you’re using SonataAdminBundle or Sylius (which are very popular solutions in Symfony) you cannot count on API Platform to create API from the code provided there.

Summary

I grew up in the gaming community where there’s the saying that good games are “easy to learn and hard to master” – I think this sentence also describes API Platform.

If you just want to quickly create a very simple API, this tool will be very suitable for you. If you want something more – it’s also possible but, unless you’re a Symfony expert, you’ll need some time and practice to achieve it.

Although I always approach fresh projects with reserve (API Platform is just a few years old now, which for me is a very short period of time), I think this framework is a very promising solution.

By releasing the second version, the guys from the core team have really shown that they were able to fix their own mistakes and were listening to the community. Most of the annoying problems from the first version were solved, for example, now there’s a possibility to use subresources from parent resource instead of creating two separate API endpoints for that. It’s a sign that the framework is going in a good direction.

To be honest, I’ve also wanted to write something about gaps in the documentation. We were even planning to release our internal subsidiary document explaining the differences between documentation on their site and the real code situation. But, meanwhile, the documentation has been updated – which also shows that the framework is still evolving and we might expect even better versions in the future.