include.image_alt

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?

include.image_alt

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.

include.image_alt
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? 200 OK, 204 No Content or 404 Not Found

include.image_alt

Generating OpenAPI Descriptions. When is it a good idea?

By Erik Wilde & Arnaud Lauret, June 1, 2021

As a follow up of my “6 reasons why generating OpenAPI sucks” post, I had the pleasure to talk about “is it a good idea to generate OpenAPI descriptions?” with Erik Wilde. In this discussion, we answer this questions at various stages of the API lifecycle: design time, code time, and runtime.

include.image_alt

/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 GET /resource. 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.

include.image_alt
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, 403 Forbidden, 404 Not Found or 410 Gone?

include.image_alt

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.

include.image_alt
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? 401 Unauthorized, 403 Forbidden or 404 Not Found?

include.image_alt

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).

include.image_alt
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?

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