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?


Le Clash REST vs GraphQL

By Nicolas Barrasson & Jonathan Jalouzot & Arnaud Lauret, December 9, 2021

L’idée folle de l’équipe Microsoft User Group France pour API Days Paris 2021: un clash REST (représenté par votre serviteur) vs GraphQL (représenté par Jonathan Jalouzot, tenancier du Meetup GraphQL Paris) arbitré par Nicolas Barrasson.


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.


Talking about The Design of Web APIs with Erik Wilde

By Erik Wilde & Arnaud Lauret, November 30, 2021

Had a great time chatting with Erik Wilde about the motivation for writing The Design of Web APIs book, and why it specifically focuses on the design aspect of the API lifecycle (and also why it is not titled The Implementation of Web APIs).


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.


Full Life Cycle API Management is not enough, let’s try 8K API Management

By Arnaud Lauret, November 17, 2021

You didn’t knew that API Management was old and you needed a “Full Life Cycle” API management solution to help you achieve your API strategy? Well, I didn’t. To be honest, though the term is quite old, I didn’t realized until recently that “Full Life Cycle API Management” started to replace simple “API Management”, at least in software vendor communications. But what if I tell you that this “Full Life Cycle” version is already dead? What if I tell you that you need 8K API Management?


We need to talk: OpenAPI 3 is 4 years old, but Swagger 2 is still predominant

By Arnaud Lauret, November 10, 2021

While quickly doing a first scan of latest Postman State of the API Report , I did my Spock face, raising an eyebrow. Indeed, I read that after JSON Schema, “The next most popular specifications were Swagger 2.0 (54%) and OpenAPI 3.0 (40%)”. To be honest and based on my own experience, it’s not totally surprising, I’m still hearing/reading “can you check that Swagger” everyday. But why the 4 years old OpenAPI 3 is still struggling to surpass the good old Swagger 2?


Choosing between birthDate and dateOfBirth has important implications for your API

By Arnaud Lauret, November 3, 2021

On LinkedIn, someone asked me what to choose between birthDate or dateOfBirth. That looks like a very simple question, but it’s absolutely not. Choosing between two names is the tree that hides the forest. Besides having impacts on understandability, choosing a name can have impacts on naming patterns, data, or privacy which are quite important topics for APIs.

By continuing to use this web site you agree with the API Handyman website privacy policy (effective date , June 28, 2020).