API Designer Experience, the other DX
By Arnaud Lauret, July 7, 2021
Nobody expects the API inquisition! Literally. When creating public or private APIs, an organization must work hard on creating the best possible developer experience or DX. That requires to ensure that API designers “do their job well”: creating APIs that fulfill actual needs and are easy to understand and use. This is the aim of governance which may help creating the best APIs or may slowly killing the organization, depending on the designer experience, the other DX, it provides.
Automate all the things (like Cloudflare cache purge) with Github actions, Postman and APIs
By Arnaud Lauret, June 30, 2021
What if I tell you can run Postman collection inside Github Actions and so easily automate all the things as long as they provide APIs? Sounds interesting right? So let me show you how I migrated my Jekyll blog publication workflow to Github Actions and how I used Postman collection to clear my Cloudflare cache. Bonus: You may also learn a few things about DX and API design.
API Design Reviews Series - Part 1
3 good reasons to do API Design Reviews
By Arnaud Lauret, June 23, 2021
More often than not when people hear “let’s do an API design review”, they hear “let’s check that an API design conforms to API design guidelines”. That’s only partially true and reducing API design reviews to that is a terrible mistake. Actually, doing API design reviews only to do that may even not make any sense at all. Let’s see 3 really good reasons to do API design reviews.
Handling breaking ch-ch-changes
By Arnaud Lauret, June 16, 2021
In (Ch-ch-) Changes, David Bowie sang “Every time I thought I’d got it made, it seemed the taste was not so sweet”, that’s a good metaphor for API design. An API will irremediably evolve because it will lack some features or because of mistakes, and so sooner or later, you may have to introduce a “breaking change”. That’s usually when people start to run in circle, scream and shout “Oh! Please no! Please, not a breaking ch-ch-change”. But, what is it actually? How to handle it? And should you always be afraid of it?
Pink Fluffy Unicorn API? WTF? (or 3 reasons why choosing a not meaningful API name can be a problem)
By Arnaud Lauret, June 9, 2021
It is usually considered a terrible practice to name a property or a function with a meaningless name when writing code. But surprisingly, when it comes to choosing application or API name, some people tend to choose names in a more artistic way (says the “API Handyman” who can name some tool “OpenAPI Chainsaw”). So let’s see 3 reasons why choosing a not meaningful API name can be a problem.
Choosing HTTP status codes Series - Part 4
Empty list, HTTP status code 200 vs 204 vs 404
By Arnaud Lauret, June 2, 2021
When designing APIs, choosing HTTP status codes is not always that obvious and prone to errors, I hope this post series will help you to avoid common mistakes and choose an adapted one according to the context.
This fourth post answers the following question: given that /users is a collection (a list) and no users are named Spock, what should return GET /users?name=spock?
204 No Content or
404 Not Found
/resources rules and /resource sucks ... or is it the other way around?
By Arnaud Lauret, May 26, 2021
Using singular or plural to represent a list of something is an old debate in computer science, especially in the database field.
But what about APIs then?
It’s still the same, if you look at various APIs, you’ll see that something like “list/search resources” could be either represented by a
GET /resources or a
Who is right?
Who is wrong?
I have a preference, you may have another, but should we really give importance to such a debate?
Aren’t we missing something?
Let’s investigate that topic and discover what’s really important when choosing collection resource path.
Choosing HTTP status codes Series - Part 3
Move along, no resource to see here (truly), HTTP status code 204 vs 403 vs 404 vs 410
By Arnaud Lauret, May 19, 2021
When designing APIs, choosing HTTP status codes is not always that obvious and prone to errors, I hope this post series will help you to avoid common mistakes and choose an adapted one according to the context. This third post answers the following question: given that resource with id 123 actually doesn’t exist in the underlying database, what should be the response to
GET /resources/123 when consumer is allowed to access such ressource?
204 No Content,
404 Not Found or
6 reasons why generating OpenAPI from code when designing and documenting APIs sucks
By Arnaud Lauret, May 12, 2021
When working with OpenAPI Specification documents to design and document APIs, there are two approaches: either you write it (directly using a text editor or indirectly using an API design GUI), either you generate it from the implementation’s code (using annotations). Generating OpenAPI Specification documents from code has major drawbacks that you should be aware of in order to choose this approach knowingly.
Choosing HTTP status codes Series - Part 2
Hands off that resource, HTTP status code 401 vs 403 vs 404
By Arnaud Lauret, May 5, 2021
When designing APIs, choosing HTTP status codes is not always that obvious and prone to errors, I hope this post series will help you to avoid common mistakes and choose an adapted one according to the context. This second post answers the following question: given that resource with id 123 actually exists in the underlying database, what should be the response to
GET /resources/123 when consumer is not allowed to access it?
403 Forbidden or
404 Not Found?