HTTP Codes are not a Suggestion
Last month, I have presented my speach about the HTTP codes. As it is always with the tehnical talks, it is interesting to see what comments and questions people give during and after the speech.
I had a very weird comment from one of the participants afterwards. He said that he does not understand, why we should not be just ignoring the HTTP codes and use the human readable explanation in the body.
I mean, I just sort of understand a bit where he is coming from. If you only even need to deal with one integration, then it only matters in the cases that libraries and browsers can deal with automatically. For example with the redirects and so on. With one integration it does not matter whenever the code for controlling the flow uses the text in the body or HTTP codes.
And I will admit that a lot of times I was saved by a better description in the body during debugging. There is nothing more helpful than actually getting back the message of what I did wrong or what I should change.
But there are a couple of potential pitfalls that are connected to this.
The first one is the problem of maintainability. If the control code is written with the body content, then this body content should not change. And I do not trust the APIs to keep the bodies of their errors consistent.
The HTTP codes can only be 3 digit integer and all defined ones already have the meaning attached. So they do not change based on the whims of every API developer.
Sure, if you can also put a more human readable description in the body, please do. I was saved multiple times during debugging by this. If the API tells you exactly what it wrong, this really helps.
I have seen the wording of the message change and I have seen the JSON structures of the error messages change. And these are the changes, that are not usually described in the change logs, assuming the API even keeps a public change log.
The second one is, that the documentation for these is usually lacking. Unless you can provide me the list of all the possible errors that you can return in the body, I will not know, if I covered everything.
I have had to resolve a lot of bugs, when we saw new error messages. This actually increases the maintenance burden on the people keeping these integrations working.
Also, I have seen cases, when the APIs do not return any error description for security reasons. This usually happens on the logging endpoint, but have seen examples elsewhere as well.
If one does not use the HTTP codes, then this is not a solution that should be available. Based on my limited knowledge of the IT management, I don't think they would take this into account.
The last one only comes in the effect, if there are a lot of integrations to maintain. Since HTTP codes are standardized, it is possible to have common flows for some of them. HTTP code 401 (Unauthorized)? There are only two flows normally possible: either authenticate again or the credentials are invalid. Most of the APIs 401 responses can be covered by this.
So if the code gets this, it knows what to do.
On the other hand, if each body provides their own explanation for this, then each integration separately needs to deal with it. There is no way to share these flows at all.
These are just a couple of examples of why I would prefer to also get a relatively correct HTTP code in addition to the body message. I hope I made you realize, that HTTP codes are important part of the communication as well.