Between stability and innovation

Nolwenn Poirier
Dec 13, 2019 · 7 min read

We proudly released our API almost three years ago, in March 2017 to be more precise. It was, in fact, one of the big new features of the 1.7 version, along with the Teamwork Assistant.

At this time, the API had a very small scope. It was focused on the products and the catalog structure. We launched it, in the hope that it would highly simplify our ecosystem’s life when it comes to PIM connectors.

Because as you may know by now, a PIM without any connection is quite useless. 😉

Watching a feature grow

3 years later, the API grew from 35 endpoints to 102 endpoints, covering 25 resources of the PIM.

PIM 2.0: 65 endpoints, PIM 2.1: 85 endpoints, PIM 2.3: 87 endpoints, PIM 3.0: 102 endpoints, PIM 3.2: 119 endpoints
PIM 2.0: 65 endpoints, PIM 2.1: 85 endpoints, PIM 2.3: 87 endpoints, PIM 3.0: 102 endpoints, PIM 3.2: 119 endpoints

With the API’s initial release in 2017, we crafted an API documentation to guide you in building connectors. Within 3 years, it attracted more than 50k visitors.

314 unique visitors by week in March 2017 to 793 unique visitors by week in December 2019
314 unique visitors by week in March 2017 to 793 unique visitors by week in December 2019

Along with the growth of our API coverage, its user base also grew. Its success translated into more and more PIM projects using the API for their entire integration. Today, it’s officially the best way to connect the PIM to third-parties and we hope it will become a standard in the future.

Speaking of which, here are a few reasons why the API is now a must-have when it comes to the PIM connectivity.

First, connecting to the PIM via the API offers the best performance. We put a great deal of effort into boosting its speed. Since version 3.2, the export performance is far better: it’s 5 times faster to export products. Also, starting from the 4.0, you will see major improvements when creating or updating products and product models: between 2 and 5 times faster. 🚀

Besides this strong argument, the API is also the only way to connect the PIM for our Serenity customers. Indeed, you cannot customize the PIM code in this SaaS mode and FTP file exchanges are not possible either. So, if you want to benefit from the Serenity automatized updates and regular feature releases, the API is the way to go to integrate your PIM in its IT environment.

Last but far from being least, the major reason why the API is the best option for the PIM connectivity is its featured stability. This point is really key as it allows our ecosystem to suffer much less when upgrading to newer PIM versions. Indeed, any API-based connector will still work whatever the PIM version you are migrating to.

Not breaking things

Stability is a huge promise. Especially when you have to guarantee it on a daily basis. For every new PIM feature, we have to make sure that it won’t break anything in the API. The rule is simple: we can add new endpoints or properties to resources, but never, ever, remove or change anything.

Let’s be honest, that’s quite tricky. Even for the “adding new endpoints” part. Even in this case, we have to think twice: we need to ensure that these endpoints will still mean something in 2 or 3 years, after 4, or even 8 new versions of the PIM.

In fact, when designing a stable API, you have to think ahead a lot, on what may or may not be coming next, in order to let your API evolve without introducing any backward compatibility breaks. It can be a real hassle sometimes. But as we know how high the cost of a PIM migration can be, we are convinced that it is really worth it. Our API must remain stable.

And since March 2017, we have been doing a pretty good job on that part. We are quite proud of being able to say it’s been 3 years and our API is stable. 3 years, it’s also 7 new versions of the PIM. It means that the 35 endpoints delivered in 1.7 are still the ones you can use today, on our latest 3.2. 💪

Welcoming the Asset Manager

When preparing the 4.0, one of the topics identified for this release was reinventing a key feature of the PIM: the Product Asset Manager, aka the PAM. Indeed, our customers asked for additional PAM features. So, we invested significant effort in thinking about how to make asset management more efficient and robust, especially when dealing with digital assets from many different sources.

Thus, we are very excited to announce, that in 4.0, a brand new experience to manage assets will be delivered.

It’s called the Asset Manager (aka AM) and it will be significantly more powerful than the PAM and we think you’re going to love it! See for yourself -here is a non-exhaustive list of what’s being cooked for the 4.0:

  • Assets are now flexible objects. They have a family, structured with attributes.
  • Assets have a completeness, like products or reference entities.
  • Assets can reference external files with URLs.
  • Assets can be automatically linked to the right products.
  • Assets have their dedicated space within the product form.

Powerful, isn’t it?

If you are interested in knowing more, don’t hesitate to take a look at the Asset Manager concepts right here.

Dealing with the PAM and the Asset Manager

Bringing to life this highly expected experience around asset management also meant that we had to make some difficult decisions regarding our old PAM. What were we going to do with this feature?

We debated whether to maintain both the PAM and the new AM at the same time in version 4.0, but we ultimately decided this would create confusion and a poor experience for our dear users. That’s why we have no choice but to entirely remove the PAM from the PIM starting from the 4.0.

This decision has an impact on the stability of our dear API as, starting from the 4.0, all the PAM endpoints will also be removed.

We tried to find ways to keep those endpoints even though the PAM feature is discontinued.

For example, we considered holding on to the PAM asset creation endpoint and using it to create an AM asset instead. However, in the Asset Manager, a family is required whenever you create an asset, a notion that doesn’t exist in the PAM. So when creating an asset by using the PAM endpoint, the PIM would have to automatically choose a family on your behalf. It is far from being acceptable as defining the right family for your assets is an actual modeling exercise and cannot be automated.

We observed the same incompatibilities for all the other PAM endpoints. In fact, there is such a big paradigm change between the PAM assets and the AM assets that we couldn’t find any acceptable way to ensure the backward compatibility of the PAM endpoints.

To be crystal clear, starting right now, the following endpoints are deprecated.

It means that you can still use them, but we strongly recommend you to take a look at our Asset Manager and its already released API documentation, especially if you are planning on using a 4.0 soon.

When the 4.0 is released, in February, the endpoints mentioned above will still be available on the 2.1 to the 3.2 versions. But, they won’t exist in version 4.0 and beyond.

In the future, we will do our best to always communicate as early as possible when we know that this kind of change is going to happen. For example, we can already tell you that we won’t break anything else, API-wise, in the year to come.

Adopting the Asset Manager

Of course, breaking the stability of our API is something that is and will remain exceptional. It was not a light decision to make but we believe it’s definitely worth it. The AM is the result of a one-year user research period. We heard you and now we are confident that this feature we built together will dramatically enhance your productivity around assets.

Regarding the migration, don’t worry. You won’t be alone in this new journey, as the whole Akeneo team will be with you every step of the way. As this situation is extraordinary, we will deploy on our side, extraordinary means and material to help you transition from our old PAM to our shiny new Asset Manager: step-by-step migration guide, scripts, workshops, and even a special APS session! So stay tuned!

Can’t wait to know more? As said earlier, you can already take a deep dive into the API documentation of the Asset Manager. You will discover its brand new concepts, how it works and also a complete guide to connect it to DAMs. You can even test the API endpoints of this feature directly on a 3.2 PIM. So don’t hesitate, play with this new API and give us your feedback. We are eager to hear your first impressions about this highly expected feature.

Akeneo Labs

Stories about Akeneo product & engineering experiments

Thanks to Nicolas Dupont, Laure Brosseau, and Morgane Nandillon

Nolwenn Poirier

Written by

Product Owner @Akeneo, enhancing the DX for our Akeneo community

Akeneo Labs

Stories about Akeneo product & engineering experiments

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade