What to consider when building an API sandbox
By Arnaud Lauret, January 26, 2022
Used through the “try it” feature of an API’s documentation or directly called by a consumer application, an API sandbox is a great way to let developers play with an API and learn how it works without giving them access to the actual production environment. But what is an “API sandbox” actually? Is it just a mock? It can be that … or far more than that. Let’s see what could be the features of an API sandbox.
A few concerns to be aware of when adding try it feature to API documentation
By Arnaud Lauret, January 19, 2022
“That’s neat! The developer portal/api documentation solution we chose comes with a try it feature. Everything is out of the box, we’ll have absolutely nothing to do to allow people test our APIs.” … If only that was true. Unfortunately, there are a few concerns to be aware of to actually propose a try it feature.
Nobody cares about API design guidelines
By Arnaud Lauret, January 12, 2022
“Did you read our API design guidelines? Yes we did! … Sorry, but I don’t think so”. Let’s be honest, besides those who write them, nobody cares about API design guidelines. Some don’t read them, some don’t agree with them. Should we punish the offenders? Though it is sometimes tempting, no. Should we get rid of API design guidelines? No, we can’t. But how can we make people care about it?
API design and architecture lessons from a frying pan
By Arnaud Lauret, January 5, 2022
In the kitchen, I’m the dishwasher. And lately, washing our new frying pans has got me thinking about design and API architecture issues. This post is dedicated to the person who complained that my book contained too many analogies. Sorry, but no matter what I do, read, look at, listen to, I’m always trying to see if I can make connections to APIs. And housework is no exception.
How to choose ids and codes to build user-friendly and interoperable APIs
By Arnaud Lauret, December 29, 2021
As an API designer, why should you care about the value of a
countryCode, or an error
Because wisely choosing the value of such (in a broad sense) “identifiers” greatly participates in the making of a user friendly API; but most importantly an interoperable one.
What should come first when designing an API?
By Arnaud Lauret, December 22, 2021
Either you provide public or private APIs, you must have a design first approach.
But what does actually mean “design first”?
Does it mean religiously writing all your
GET /this and
POST /that in an OpenAPI file?
But if that so, how is this so different from the code first approach where you write actual code to generate an OpenAPI file?
Maybe it’s time to clarify what should come first when designing API.
Handle API gateway and backend differences in API documentation with OpenAPI Specification
By Arnaud Lauret, December 15, 2021
I got yet another interesting question from my social networks: how to deal with the fact that an API contract can be different at gateway and implementation levels, and more precisely how to manage that when describing that contract with an OpenAPI file used as specification targeting API’s implementation’s developer and documentation targeting API’s consumers?
And what if I’m wrong? Overcoming fears and doubts while designing APIs
By Arnaud Lauret, December 8, 2021
F*** impostor syndrome, it’s not easy to say that I’m an API design expert, but I am. Along my path to expertise, I failed, I did mistakes; that helped me to learn a lot. I also have been afraid, I had doubts. And you know what? Though I’m now an expert, that’s still the case when I help people to design their APIs. But, I learned to live with that. I learned to live with the “what if I’m wrong” question.
5 reasons why you should treat private APIs like public ones
By Arnaud Lauret, December 1, 2021
“Why should we care about our privates APIs? They’re only consumed by us, so let’s do minimal work on them. We’ll keep our effort only for the public ones we sell to the outside world.” Such stance will have terrible consequences for an organization, even more if it will never create public APIs. Let’s see 5 reasons why you should treat privates APIs like public ones.
5 ways to update a boolean status with a REST API
By Arnaud Lauret, November 24, 2021
Last week, someone sent me a direct message on Twitter asking the following question: Let’s say you have a resource with an activated boolean property, how would you design the operation(s) allowing to activate or deactivate it? As this is a use case I often encounter during API design reviews or API design workshops, I thought it would be interesting to share my usual answer(s) with everyone.