Building Better REST APIs

Mateus Canello Ottoni on July 16, 2017

This post was originally posted on Medium. I’ve worked as a software developer for almost five years now, most of this time focused on develo... [Read Full]
markdown guide

It seems like in the section about Long-Running tasks, you're describing a pattern that would and could be better served by message queuing. This is great because long running tasks can happen in the background without forcing your customer to wait since this is asynchronous. My team uses the pattern:

  1. Receive the request.
  2. Gather any other data needed.
  3. Send the message to the message broker to be queued.
  4. API responds with a 202 - Accepted and a JSON body that contains a URL that a client can "poll" for status if necessary.

Meanwhile, the message is sent by the broker to a waiting "worker" that will process the message and perform any sort of updates needed to the application/service backing store to let anyone interested know that the work has been done.


Thanks for the nice article, Mateus! I will definitely look more into headers as a way to communicate information to the consumers of my APIs.
One thing that I strongly want to point out is that there is no such thing as reusing a thread. A thread is started with a certain task and cannot be reused. Rather other threads can run and utilize the CPU cycles that would otherwise be wasted. An efficient idea of this is a ThreadPool.


Perhaps I have expressed in a wrong way, but what I did have in mind while writing about the threads was actually the thread pool system. I apologize for the misunderstanding.


Really nice article discussing the subject which is one of the keywords in market today.

I too have worked on Rest and find it really a good tool, but being pragmatic is the way to go when designing any api.

The martinfowler.com/articles/richards... provides good guidelines regarding how to be pragmatic when designing any endpoint.


Great post, but you have missed an important http status Code. The 418 I am a teapot has to be in every API 😉

code of conduct - report abuse