By now, you’re probably tired and annoyed with me talking about HTTP messaging. But it’s important! It’s the backbone of how the internet communicates between networks and computers and I wouldn’t be doing my job if I didn’t harp on this.

With these past few articles, I’ve been trying to point you, reader, to the tools built into the HTTP protocol to enhance your APIs. The last piece of the puzzle is to determine what actually happened on the server side. I could very well give you a widget creation form, you could send the form and I could just give you a success message, no matter what. But what if, then, you went back to the widget list, and didn’t see the newly created widget! I’m sure to get calls about this one!

There are some valid reasons why you’d expect the list to not be fully up to date mere seconds after submitting the creation form. If you’re doing an asynchronous creation through a queue like AMQP or a cloud service like Azure Storage Queues, it will take a little time, depending on how busy the queue is. If it takes more than a few seconds, you’ll want to consider either upping the number of workers, upping the queue’s resources, or, and this is probably the first solution you should try, optimizing your software. If you’re relying on database replication to write to a main database and read from a secondary database (see note), the replication might be a handful of seconds off.

But let’s assume you’re doing a simple synchronous call to a server to create a widget. How do we know that it succeeded? We could send an error message and, in the absence of an error message, assume everything went A-Okay. But that, in and of itself, is error prone. So we rely on HTTP header status codes. For a widget creation form, send back a status of 201 Created.

I like this chart that I shamelessly stole from a meme. If anyone can tell me who it’s from, comment and I’ll make the change.

For instance, if you are looking at a web page that you typed into the URL bar and you saw an actual web page, the response is likely 200 OK. As mentioned above, if you fill out a form and don’t get an error message back, then it should be 201 Created. 404 Not Found is a favorite. And then there’s the dreaded 502 Bad Gateway. My favorite (yes, I have a favorite, no, I don’t need an intervention) is a joke (big surprise there!) is 418 I'm a teapot: The server refuses the attempt to brew coffee with a teapot. I find it useful when debugging code that may have multiple reasons to give you a 401 Bad Request code. Just replace the 401s with 418s, and run the code a handful of times. When you get the 418 response, you know where your code is failing.

Source

HTTP Response Codes

Note: I absolutely hate the names “master” and “slave” for databases. This is problematic, and database vendors REALLY need to get to work on relabeling these. Github is now using “main” as the default branch name, in lieu of “master.” Which got a lot of bees in certain people’s bonnets, but really, guys? I applaud that move and hope that the entire tech community looks at their nomenclature, to make sure we’re not using hurtful language. Words matter! </rant>