You should not just jump to libraries

As part of Platform of Trust future I’ve been tossing the idea of libraries since March. So far we have provided just APIs, but the amount of APIs is rising. This means that platform consumers need to learn more and more APIs. We are developing still maturing platform and the APIs pop up like mushrooms after the summer. At the same time existing APIs are updated as we learn from first customer cases. The changes are sometimes even backwards breaking. But that is not a problem to our first customers; they acknowledge that we are building together something rather complex.

Using the platform looks and feels complex now, but after we have gone a little further pieces just fit together and all seems so simple. In short, APIs change all the time, new APIs come along as we go forward. It seems that we are pushing microservice APIs to public level as such. You can imagine that it results to plethora of APIs. Not a good situation, but options are rare. This is how we decided to start the platform development. Get the first customers onboard fast and learn together with them. Is this the moment to build libraries?

No, it’s not. I see that two things will happen in the following order:

After that we are ready to jump into library bandwagon, not before.

Freeze the APIs

One remedy is to reorder endpoints in APIs so that we can have less individual APIs. We have to o this and plan is that rest of the year our APIs are free to change even with backwards breaking changes. Last day of this year is the moment we freeze version 1 APIs. After that all backwards breaking changes go to version 2. If we don’t fix the version and build the libraries on top of the APIs we end up in situation and that we are updating constantly the APIs and libraries. Every backwards breaking change will break the libraries.

So far our APIs have been developed code-first because that is just faster at least in our case. Now we have plan to move to Design-First development workflow. The reason is that with desing-first we gain sustainability and better customer interaction without wasting resources.

Reorder endpoints

At the same time we will reorder the endpoints in various APIs so that we have less APIs, but the same amount of functionality. We are now almost the developer experience nightmare since our APIs are wild and changing all the time. Developer eXperience is not in shape. But you can’t make an omelet without breaking some eggs. This is planned activity and we know how and when we achieve the wanted great Developer eXperience. We could drop this reordering step if we would “hide” the APIs, but we will keep them available for now. In the long run we might make it less obvious to find APIs, but push the library solutions to all developers. Of course the APIs and documentation will remain available, but it’s not the first thing you’ll see in the Developer Portal.

Libraries on top of solid APIs

If you look at for example highly successful and loved Stripe, you see that they push libraries, not APIs. Same applies to SendGrid and many others. The library-driven platform-ish solutions like Stripe maintain some libraries themselves and have managed to get developer community to create more libraries. Keep in mind that maintaining the libraries takes resources as well.

Why libraries? First obvious benefit is that libraries make service consumption easier even compared to APIs. Keep in mind that some operations might need multiple API calls from separate APIs. Which is easier, learn and consume multiple APIs or use library which offers 2-3 lines function to get same thing done?

Simplified DX with libraries

Another thing is versioning and documentation. When your consumers are using multiple APIs, those APIs might have different versions. They probably do not live in the same version cycle. Then the developer is in a version and API hell. There’s plenty of risk factors and shit will hit the fan eventually for multiple developers. Now if you have library, you need to keep that updated and related documentation. The library uses the underlying APIs but developer does not need to worry about the versioning and other things.

Some more to read from 100 Days DX