As you could see already in the Sylius 1.7 release blog post or on our repository, we are working heavily with API Platform integration. It is something that has been in our heads for a long time and we wanted to make a good, thoughtful decision. Are you wondering why? Are you concerned about the future of Sylius API? If yes, then this blog post just may answer your questions. 😉

It is reasonable to discuss the background of what we have decided on before we will talk about our recent decisions and reasoning behind them.

Admin API

Sylius was always meant to be a modular solution. Out of the box, it is served with three infrastructure layers: Admin, Shop and Admin API (where each of them can be disabled in case you don’t need them). Admin API is the oldest Sylius API, which has been with us since 2014. This is an API described in our docs and it was meant for integration with external systems from day one. Therefore, it’s responses are bloated with data and allow for almost all operations that are available in the Admin panel. And it is ok, it looked like this by design and it played well. This API had some really nice features:

• It was using the same controller and architecture as default Sylius implementation – therefore, once you understood key Sylius concepts, you’ve already known how to customize Admin API
• It was a RESTful API, with some hypermedia links already there

However, it had a set of drawbacks, that made it harder to do a full-fledged API first shop implementation. Business logic could leak to the frontend part (like deciding if order items should be merged or not, or deciding which price should be displayed). It wasn’t that easy to customize object serialization as well. If one would like to customize serialization for one of the classes in the core, they would be forced to override serialization of all items in the core. And last, but not the least, we haven’t chosen any official API standard (like JSON API, LD-JSON or HAL, however, HAL support was the closest). 

So we had decided that the creation of a frontend friendly API is the next step for us. 

Shop API

We’d already been equipped with knowledge about the strengths and weaknesses of the current Admin API. Next iteration over our API brought a bunch of improvements:

• We decoupled our business logic (application) from the infrastructure with the command pattern. This approach works great with exposing behavior-oriented operations like cart operations (adding, removing items to the cart, processing with checkout, etc.). It allows keeping a single source of truth for business operations and provides a way to customize them with ease (either through decoration or replacing logic with your own)
• Requests and responses were simplified. All the logic of how the product should be resolved and if it should be reflected as a new order item or merged to the existing one was transparent to the API client. Returned responses were already translated and adjusted based on the channel configuration
• To improve DX when working with returned data, we introduced view objects, which were meant to contain only the required data for frontend and were simple POPO (Plain Old Php Object).

On the other hand, these improvements came with a trade-off. We introduced brand new architecture concepts, hence one couldn’t simply use the same approach to customize Sylius behavior as in the core. Not all operations fitted the command pattern approach and it would be better to leave a CRUD based behavior on them. Because of some changes in the response structure, a hybrid approach (with command pattern and what you already know from Admin API) was also not the optimal solution, however the best possible compromise at that moment. Some set of problems persisted in this approach as well, such as problems with data serialization or documentation, which had to be updated manually. What is also worth mentioning is that this API was a RESTish implementation, so we followed most of the recommendations, but you couldn’t find a link between resources in most of the cases.

Brave new world

All these experiences have led us up to this moment. Now, we have to unify the usage of our API’s, to make the structure more predictable. It should be much easier to customize entities and it’s serializations, while business processes should be centralized and easy to be replaced. Documentation should be generated from the configuration to always be up-to-date. We also need some way to enforce feature parity between HTML based UI and API. At the current stage, both of them should be treated as first-class citizens. Furthermore, we should follow one of the available paradigms for an API. 

Building on the shoulders of giants and the usage of standardized solutions was always important for us. There is no need to reinvent the wheel when available solutions are battle-tested already. It’s much better to collaborate with others to achieve our common goals. FOS Rest Bundle is not a Symfony standard for API creation anymore, and JMS Serializer has a serious competitor, which is Symfony Serializer. Sylius was a standard Symfony app from day one, and we have always been extending its powers rather than replacing them with our own solution. Wherever we could, we strived to do it just in a Symfony way.

This brought us to the biggest cooperation of open source projects (at least according to my knowledge) in the Symfony ecosystem. This cooperation was possible only because both projects decided that they do not want to reinvent the wheel and stay as close as possible to the standard Symfony approach.

 We have decided that we should rebuild our API and use API Platform to build a truly mature, multi-purpose API which can define a new standard for headless e-commerce backends. 

API Platform provides a firm foundation for API projects. Content negotiation and support for several API standards will give us the possibility to support the most mature solutions, while not force users to use our recommendation. It comes with OpenAPI specification based on the current configuration, so documentation will no longer be outdated. Both API Platform and Symfony Serializer will bring us even closer to the Symfony ecosystem. 

Thanks to our BDD approach and business-oriented feature description we want to ensure feature parity. Both HTML based frontend and API will have the same setup executed, while we change the interpretation of customer actions on the website and use API calls instead of clicking on the website for the new stuff. But this is a story for another blog post 😉

What does it mean?

First of all, it means that we will be supporting API Platform out-of-the-box. Secondly, it means that both APIs will be deprecated. We are not dropping them right now, but they will not receive further development. In the later phase, we should provide an upgrade path for currently working apps. Last, but not least, you can already track our progress. All the PR’s will be aggregated here and the documentation can be already found here. Would you like to help us with it? 

Please, visit the: https://github.com/Sylius/Sylius/issues/11250, grab one of the issues and contribute to Sylius!
Let’s create the best e-commerce API together!