Site API for eZ Platform: docs, workshop video and more

I joined eZ System's core development team at the beginning of 2012., for the rewrite of eZ Publish that became version 5, and was part of it for the next 5 years or so. With the rewrite, we kept the content model, but everything else had to be re-developed from scratch. That was a huge task, so for a time, we sported a dual-stack approach, with both new and Legacy kernel available at the same time. That was needed to ease the transition to the new stack, but of course Legacy had to be dropped at some point. The drop happened with the rebranding to eZ Platform, released at the end of 2015. The current version of eZ Platform is 2.3, but it’s still the same architecture introduced with version 5 rewrite.

Sometime in 2016. I left the team to work on Netgen’s projects again. Having to work with the product, instead of developing it, made me realise that developer experience on our platform of choice could be improved. That was the motive to start developing Site API, our productivity layer for eZ Platform.

Why Site API

That was more than two years ago. Since then, while working with colleagues involved in projects making the transition from the Legacy Stack to the new stack, I saw those who were not PHP developers struggle. Frontend developers, site builders and even PMs were able to do a lot in Legacy Stack, because it didn't require a lot of PHP know-how. A big part of developing websites doesn't require coding at all, and the part that does is mostly about the content. With eZ  Platform, that means stuff like languages, content types, location tree, relations, tags and so on. It's about modelling the website's content and presenting it to the user, and with smaller or simpler projects it can often be all about that. In Legacy Stack you didn't need PHP to do most of it. For some things you did need PHP, but these were relatively few and far between, and then you usually had a dedicated PHP developer who could do that part of the job.

Enter version 5 rewrite, and suddenly, you need PHP to do almost any kind of work. Some things to which you didn't pay attention before, like language fallback, became something you had to be aware of at all times. In retrospect, I believe it was not necessary. This shift was very disruptive to us. Roles like project managers, frontend/view developers, content builders and others went from a place where they were able to do a big chunk of the work independently, to a new place, where the same kind of work required a skilled PHP developer.

The consequence was that we became significantly less productive and for smaller size projects we were not competitive anymore. We shifted to bigger projects that required stricter separation of roles, but the problem remained. The base part of the job became more complicated, took more time and for some even fell out of reach.

Main features for better DX

These are the reasons we invested much effort into the Site API. After a bit more than two years of development and several significant additions, we now believe to finally have something that makes the development with eZ easy again. Also, it manages to do it cleanly. It opens the platform to the newcomers and people who are not dedicated PHP developers. Feedback from the former Legacy Stack developers makes us believe that developer experience is actually better than it ever was in Legacy Stack. Here's an overview of the main features:

• Transparent handling of language fallback

  Transparent handling of language fallback is something you didn’t have to think about in Legacy Stack, but it’s still not adequately solved in the new stack. We do it the right way, and you always work only with the one translation to render on a siteaccess. That includes Content, Locations and relations. This feature alone frees developers from a big part of the unnecessary cognitive load.

• Simple traversal of the content model

  Values objects contain lazy-loaded properties and methods that enable simple traversal of the content model. These same objects exist in the templates, and it’s all available from Twig as well: accessing Content relations, owner user, main Location, Location’s parent, children, siblings, filtering them by content type and creating paginations. It’s somewhat similar to fetch functions from Legacy Stack, but it's available from the objects, and it doesn’t try to cover everything, only the most commonly used features. This approach follows the Pareto principle, where only 20% of the functionality is usually enough for 80% of cases. All of it is available without any additional code.

• QueryTypes, but on steroids

  Site API elevates this simple feature from the eZ kernel and puts it on steroids. Query types provide simplified but still powerful access to search through view configuration that aims to be sufficient for most use cases. You're able to define queries for relations, Location children/siblings/subtree, filter it all by content type, section, object state, depth, priority, Content fields and more. We could again draw the parallel with fetch functions from Legacy Stack. The big difference is that instead of pulling the data in, from inside the template, you now inject it from the outside. That keeps the templates clean and gives you a better overview and control.

  It’s possible to define reusable/named queries, define any number of queries per view and with any controller. We provide many query types that you can use out-of-the-box, and you only need to write new queries in PHP for special use cases.

Documentation and the recorded workshop video

This Web Summer Camp I held a workshop about the Site API. In the first part of it, I talked about developer experience with eZ Platform that I summarised above: where we were with Legacy Stack, where we are now with eZ Platform and how it all came to be. In the second part, Mario Blažek and I showed what Site API does to improve the situation. Here's the video:

The feedback was very positive, and it confirmed our experience. Since then we decided to invest time into proper documentation so that more people can benefit from it. The documentation is one significant addition for the 2.6 release. It uses ReadTheDocs service, which means it's open to contributions. You can find the source on the Site API repository on Github, and the build is available at https://docs.netgen.io/projects/site-api/en/latest/. Do take a look, and let us know what you think.