What is a REST API?

The use of Best Practices

Since a couple of years ago I have been adopting the use of best practices to design and build better software solutions. This all started while I was working for Bluekite a startup that was disrupting the cross-border payments industry, we were a small group of young Software Engineers who changed themselves into a strong team of Pragmatic Developers.

We started adapting Best Practices to almost every piece of software, Javier who was a Senior Developer talked us about this book Patterns of Enterprise Application Architecture from Martin Fowler (considered a Software Architect Guru) that had a lot of common patterns. This book describes some of the most important patterns in the Software industry, from Data Source Architectural Patterns, Object relational patterns to Web presentation patterns (MVC for instance). You can go deep in these topics there is a lot of theory and examples of why following a set of best practices will save you time, effort and why not? … Money.


So what is REST anyways?

REST means Representational State Transfer, It is a thesis paper from Roy fielding one of the folks behind the foundation of the internet. He was inspired by the way the WWW scaled organically and he came up with some ideals or constrains of what should have (ideally) a large scale distributed network based systems. So basically REST is a set of ideals (patterns) of how to build a system of this nature.

These are some of the constraints that REST propose:

Client — Server

This logic separation is important, a long time ago (and in some old and large institutions still use this). The Client was concerned about the data and some logic of the Server, because these two were mixed somehow in the same system. REST propose a separation with the following concepts in mind:

  • Client fetches the data using defined services from the Server, ignoring the complexity of a Server.
  • Server is a isolated instance that throws responses based on requests, the server is the only one who knows about the data structure. Servers are not concerned about the user state, this makes it simple and scalable.
  • Stateless, Restful interactions are stateless.
  • This means that the server ‘forgets’ the knowledge between requests.
  • Once the Server response it’s done, there is no caching or persistence of what you have been requesting. So again, each request is processed independently from the other requests.


Use nouns not verbs, HTTP already provides verbs, no need for ‘get_user_by_id’ names in the URL. Follow the HTTP verbs:

  • GET (To give me a representation).
  • POST (To Create).
  • PATCH (To Update).
  • DELETE (To Destroy).

Basic example

When you are designing a REST API you want to provide the explicits and consistent way to interact with your services. The developers who will integrate your API should feel like it’s almost predictable the way they can fetch our data.

Alright, this was a brief introduction to the REST concepts. In the next post we will work on a simple REST API to have hands-on the requests and responses.

Show your support

Clapping shows how much you appreciated Edwin M’s story.