/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?
Adopt and not assess OpenAPI linters and other thoughts reading Thoughtworks Technology Radar 24
By Arnaud Lauret, April 28, 2021
Thoughtworks Technology Radar 24, an “opinionated guide to technology frontiers”, came out last 15th of April, 2021 and I thought it could be interesting to read it from an API perspective, hence this post sharing my thoughts on it. As always it is really interesting and full of valuable insights, though I nearly fell off my chair while reading the Tools section which talks about OpenAPI linters (if it’s not a click bait, I don’t know what it is).
Choosing HTTP status codes Series - Part 1
This is not the HTTP method you're looking for, HTTP status code 404 vs 405 vs 501
By Arnaud Lauret, April 21, 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 first post answers the following question: given that a
GET /resources/123 request returns a
200 OK, what should be the response to
DELETE /resources/123 if
DELETE method is not implemented?
404 Not Found,
405 Method Not Allowed or
501 Not Implemented?
When unicorn poop hits the fan (or how APIs can improve how we build software)
By Arnaud Lauret, April 14, 2021
Do you know what happens when you throw unicorn poop into a fan? It makes everything better, everyone and everything around looks perfect, covered with joy and happiness. Working seriously on (public or private) APIs can lead to the same kind of effect on how we build software. Why? Because modern web APIs raises the bar of software design and developer experience and so raises awareness and expectations regarding these topics for software in general.
Batch (Github) API calls with CSV and Postman runner and visualizer
By Arnaud Lauret, April 7, 2021
Do you need to make a repetitive task that could be done through an API instead of a UI? Do you need to make many API calls but don’t want to code? This post is made for you: you’ll learn to use Postman and CSV files to batch API calls. You may also learn a thing or two about API design, Github APIs (yes, plural) and other Postman features (variables, security, command line, visualizer, …) in the making. If you never have used Postman or Github APIs, no problem, everything will be explained.
7 ways leading to wrong ownership and killing APIs
By Arnaud Lauret, March 28, 2021
After hundreds of API design reviews, I can tell that the most neglected aspect of API governance is ownership. Unfortunately, that’s probably the most important one. Without true ownership, your APIs will probably be totally wrong. Without true ownership, your employees will be terribly sad or leave. Without true ownership, your company may even die. As an API design reviewer, I believe that my role is also to warn the teams I’m working with about this topic and help them to fix the problem.
API Days Interface 2020 Series - Part 2
Doing APIs right and doing right APIs
By Arnaud Lauret, July 26, 2020
API Days Interface being online made the experience a bit different but after 3 days, I felt almost as usual; exhausted and my brain boiling. In previous post, I shared my feelings about my first online conference. Now let’s talk about the content; Sam Newman doing a facepalm, API design, architecture, governance and my new favorite quote “Doing APIs right, doing right APIs”.