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

Is it possible to create a useful API in the course of a day or two? That’s exactly what the authors of the new framework called API Platform promise to us. However, you probably wonder if it’s really worthwhile to spend time getting to know yet another tool. Well, it depends.

One of the most important challenges in the software development is to “not reinvent the wheel”. That’s why, from the beginning of the history of coding, developers have tried to create solutions that’d speed up their work by automating the most repetitive processes. However, selecting tools that’ll really meet your requirements is almost always a painful procedure.

Among the most promising frameworks/tools that have shown up in the PHP world recently is API Platform. In my work, I often consult solutions with my clients — who usually are CTOs as myself. And now, more and more often, I get questions about API Platform. Is it really a useful framework or just some temporary hype? We’ve used API Platform in The Software House in a dozen of projects now, therefore, I feel like I already have enough experience to share with you some of our thoughts.

OK, what’s that?

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 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, it’s a tool based on the PHP Symfony framework which helps you speed up building the backend part of your project.

Especially in the beginning of the development process (but sometimes on 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 authorisation 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 which 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 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 exactly does API Platform give us from the beginning?

Here’s the list of my favourites:

• A ready-to-use API based on REST with a variety of formats to choose — 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 optimised and shipped with a caching mechanism (Varnish).
• There’s an automatically-generated documentation (we all know how much developers hate to write any docs, leave alone supporting them in a 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 estimation for building from scratch an API which, 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 authorisation, 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.

OK, I know what you’re thinking at this moment:

RAD is only good at the beginning, as when you go deeper, there are always problems. 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 customised controllers. And both solutions require pretty good knowledge of Symfony — the framework on which everything’s built here (I’ll get back to it later).

API Platform’s documentation used to be one of its biggest flaws but now it’s updated and very useful

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 customise it exactly as you wish. I’ve also seen frontend developers who wanted to specialise their app on 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 which 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 deeply should I know Symfony before using API Platform?

As I wrote above, if you really need to do advanced things in 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: https://symfony.com/doc/current/components/http_kernel.html. 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’s transferred via API goes through a serialisation component built in Symfony. You can find the documentation here: https://symfony.com/doc/current/components/serializer.html. If you’re wondering why the given field or structure isn’t displayed in the GET method, the issue probably lays in the serialisation.
• 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: http://symfony.com/doc/current/components/dependency_injection.html. As you might suspect, 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 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 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’ a link for further reading: http://php-annotations.readthedocs.io/en/latest/UsingAnnotations.html. Of course, you can still use XML or YAML but I strongly recommend to get 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 other. 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 developer from making a mess in the code which was one of the biggest problems in PHP some time ago.

API Platform’s pet spider showing his love for other frameworks — especially Symfony

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

Like all frameworks, 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.

Second thing is the naming convention. Like any other CRUD solution, 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 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.

As 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 2 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 about half a year ago, 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 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.

The article was written by Marek Gajda and was first published on The Software House Blog. Visit the blog for more articles on best development practices and software outsourcing tips.