I like to call my thinking as “practically lazy bastard”. What ever can be automated, must be automated. Of course the rule has execptions and one of those is that the effort needed to automate a task must not exceed the value gained from it. But in my area of responsibilities I’m not thinking short term, but often rather long term.

Thus something that might look like a small thing and can easily be done manually, often gets automated. In long term for example a small time saving gained returns enough value. That’s why my mind is set as default towards automation. Code and documentation generation is one of the juicy automation spots. Often the generation is related to libraries which are used instead of the API directly.

Dispite of the rather negative title in this post, I love code generation. But I dislike the short-sighted ignorant marketing bullshit that “any code can be generated and that’s all we need”. Yes, you can generate code, but in some situations the result does more damage than anything else. You might survive with ready-made tools but more often optimal solution requires in-house solutions. I do not accept mediocre results.

Stripe is known for “6 LOC experience”, you can get things started/done with 6 lines of code. That is achieved by using their library. That is the first thing I remember about Stripe. It’s not the thing they do, but how easy it is. It’s so damn simple to get complex stuff done. You can use the APIs as well, but most developers I’ve discussed with say that they go for the lib because it’s just so simple.

What do the client libraries then do?

Client libraries codify API requests and authentication processes as if they were native functionalities of the given programming language, automatically format API responses to match the data types used in the programming language. Benefits are obvious:

Which programming languages/environment to support?

Which programming languages or runtime environment should be support? Is it enough if we provide library for Node.js? What about python lovers? Then there are some rubyists as well?

Well, you need to know your customers and most likely use cases and contexts. Rest is just analytics and some luck. Are the most likely library users coming from rust or node.js ecosystem? You should get to know your user base and find out what kind of tools and environments they prefer to use. Then of course your client base might be scattered on three different programming languages or different variants of runtime environments (for example in java). The result is that you need to have multiple client libraries to cover desired amount of the developer needs.

Generation tools to the rescue…

At this point someone says to you that there are tools around OpenAPI spec which can generate the clients for you. To some extend I agree. If you’re using OpenAPI, you can very easily generate client libraries with a tool like OpenAPI Generator

# install the latest version of "openapi-generator-cli"
npm install @openapitools/openapi-generator-cli -g

# generate a ruby client from a valid petstore.yaml spec file
openapi-generator generate -i petstore.yaml -g ruby -o /tmp/test/

or Swagger Codegen.

If your API is simple, then the above probably works 99% of the cases. But what is the value of library built on top of one API? In some cases it might be worth the effort especially if that is generated. The bigger value would be achieved if the library makes complex API usage a lot easier. But in those cases generator probably fails.

The same thoughts and results were found by Avital from Kaltura. There is a good story of client generation in Nordic APIs, in which it is stated that “generated code tends to impose constraints, and constraints tend to result in poor developer experiences. While automation is generally a good thing, you definitely need to watch out for such incongruities.”

Your option is to accept the half-ready generation and fix the rest manually. That will become a burden to you, but if it’s necessary to your business you probably do it. Or then you build the tool needed in-house.

Biggest value requires often in-house tool development

The even bigger value of libraries are gained when multiple APIs are bundled inside a library. The developer does not need to learn to use 3-4 APIs, but instead installs one library and then learns how to use it. This kind of libraries can not be generated with the solutions in the markets. You do not want to generate and maintain the library or libraries manually. That is a tool you’ll build inhouse. You want to invest 10 000€ to a tool that eliminates human errors, enables you to build new library automatically every time one of the APIs change and.

Just like with mythical man month, in which "adding manpower to a late software project makes it later", with client code generation "adding more crappy code to the pile makes developers more angry".

Own hands-on experiences

We did an experiment during the summer 2019 in Platform of Trust with code example generation. It’s not the same as client generation, not even nearly. We were not satisfied with the results and options offered by ready-made code example generators. We pushed the challenge to one of the subcontractors who worked in close co-operation with couple of our devs for about a month (July).

The result was more than just code generation:

Our QA people got interested about the solution as well since they can use the generated code examples in API testing as well. And even if the code examples would not fit their needs perfectly, they can use the engine to generate exactly what is needed.

I have a hunch that at the point we are going to start offering client libraries, we have to do the same again. Build the perfectly fitting tool for our needs. A tool that generates 2-3 libraries fulfilling typical use cases in which you would need to use multiple APIs. All that has to be automated and generated libraries have to bee automatically tested. Anything less is a failure. That is most likely early 2020.

Dispite of the critical sounding attitude I encourage you to seek automated and generated Developer eXperience solutions

Gap in #100DaysDX series

There’s going to be a 2-day gap in the posts. I will go to Stockholm with my wife to watch Track and field 24-25 August. I need the moment with my wife away from 6 kids at home.

Some more to read from 100 Days DX