DX, API Design & Documentation

When we have a hammer, all problems resemble nails.


APIs are the kingpins of the Web. It’s enough to simply excel in the art of their development so we can build a magnificent cathedral together and not create a horrendous mess. It’s for this reason that the author of the book, ‘The Design of Web APIs’, Arnaud Lauret wanted to answer our questions.


Hello Arnaud Lauret, why did you decide to write this book now?

Arnaud Lauret : Web APIs or simply, APIs, are the programming interfaces that allow software components to communicate between themselves. Originally, I mundanely started to write ‘The Design of Web APIs’ to help others design good APIs while avoiding the pitfalls and gaining knowledge of the principals and tips that we discover and master over years of practice in advance. However, the topic of APIs has a far greater significance.

APIs are everywhere. Without them, our world that depends on computing and the internet, simply wouldn’t function. After being small workings hidden in the depths of the IT vessel for a long time, the APIs then became key components in the IT strategy but also in business.  

The experts in APIs, and myself being the first, promised the sun and the moon. For IT, APIs make the systems more simple, flexible and endlessly reusable in order to meet needs in record time. For businesses, APIs allow you to expand your offer quickly with the APIs supplied by third parties or open new channels of distribution or acquisition or access newer markets providing their services or new services in the form of APIs.  

But all these promises won’t be fulfilled if, and only if the design of these said APIs is actually good. On a small scale, a good API allows you to revisit your web subscription funnel to get a better conversion rate or to easily integrate with one or a dozen partners, and everything at a reduced price and with a reduced time to market. On a large scale, an API vision that was pushed to the extreme made huge success stories for Amazon, Stripe and Twilio. On the other hand, I know a few companies that were kicking themselves because of the enormous costs of integration and even losing a few calls for tender simply because their APIs weren’t up to standard.

Thus, the API design has a major impact on IT and business. So, in retrospect, I can say that I wrote this book to allow companies to capitalize on strong foundations in order to build a real computing or business API strategy and avoid sinking on the final stretch because of a risky design that could have been avoided (it’s more marketable!).

A page of your book, or a passage, that represents you the best?

A.L. : The API designers have a lot to learn about the user interface design of everyday objects. Whether it’s about physical interfaces (doors, electrical appliances or TV remote controls) or virtual interfaces (websites or mobile applications), all share common principal designs that equally have to be applied to the API design. Choosing a correct approach is one of the most crucial aspects for the design of all interfaces and for APIs.

Concentrate on what’s happening under the hood and it will end in a complete disaster. Concentrate on what users can do and everything will go well.

When designing APIs, separating these two approaches and understanding them is not always easy in the beginning. However, everything becomes easy when incorporating them in the real world, and the way in which these two approaches can affect the API design becomes easier to understand.

The recently emerged tendencies that you believe in the most?

A.L. : The internal UX and at all levels. I am always amazed at the capacity that we have collectively in companies, to choose/ design/create/ execute solutions proposing the most disastrous user experience possible when users are in-company. What employee hasn’t complained about the ergonomy of the holiday tracking tool or the management of requests? What ops have not complained about an architecture composed of 267 microservices using 67 different technologies, certain, still in alpha stage incompatible with a production run. What developer hasn’t whined when trying to launch an application on their computer before it’s modification because the code repository didn’t contain any explanation or assistance to help you begin.

So much cash savings but also time or simply less stress, could be done if we paid enough attention to the experience of our employees and colleagues than to our sacrosanct clients. From an IT point of view, working on APIs and the famous DX (developer experience) allowed me to become aware of this and always be careful when I’m building. Everything has to be easily understandable, usable, deployable, and maintainable over time and either it is a simple tool for the analysis of an API design from the command line, an API implementation or a more complete design. Putting a bit of empathy into what we are doing can have a big effect.

If you had to give one piece of advice to a reader, what would it be ?

A.L. : An IT architect tip that is equally worthy. The answer to all the questions of the universe isn’t 42 but “that depends”. It’s always necessary to come back to the needs, the context and the restrictions before choosing a solution and evaluating the consequences objectively.

And in technology, where a lot of people think, ‘what I do is better’, ‘what others do (or the old me from 2 years ago) is s***’ or ‘if <the startup of the moment>does that, we have to do that’, it isn’t always easy to be objective. We have to be wary of habits, and to paraphrase Maslow, when we have a hammer, all problems resemble nails. We have to be wary of hype, because the new framework/tool/paradigm isn’t necessarily the silver bullet and the magic solution to all your problems.  

In one word, what are the next topics that you are passionate about ?

A.L. :  I have two. The first is the event driven architecture, not directly from a purely technical angle (who said Kafka), but more so from a design angle. I hope that I can capitalize on the principles of API design, but I am certainly going to discover the problematics specific to this method of communication between systems and maybe one day I will write ‘The Design of Events’.

The second is the training. Being an expert in API design in your company is good, but the aim of the game is that others become experts as well. I’m going to work on how to efficiently train all the other people who have to design APIs by mixing between in-classroom training (well, via video conference for the moment) and self-service training.

Thanks Arnaud

Thanks Bertrand

The book: The Design of Web APIs, Arnaud Lauret, Manning Publication, 2020.

Original interview published in French on Jouvenot.com: http://jouvenot.com/quand-on-a-un-marteau-tous-les-problemes-ressemblent-a-des-clous/

Bertrand Jouvenot

Bertrand Jouvenot

Advisor | Author | Speaker | Blogueur

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture