History Lesson

Before we talk about what REST is, first let's look at why was REST created. Back in the 1990s the internet was a lot more chaotic and standardization was not a primary concern. As you can imagine there was no standard on how APIs should be designed, maintained and used. SOAP existed, but it was deemed messy, hard to troubleshoot and all around difficult to work with. In 2000, American Computer Scientist Roy Fielding wrote his doctoral dissertation with one goal in mind, to create a standardized set of rules so that any server could talk to any other server. Finally, REST was born.

So What is REST?

If you're an emerging web developer you've probably heard the term REST or Restful services thrown around on occasion. REST stands for REpresentational State Transfer and REST and is simply an architectural choice when developing modern web applications. Typically, systems that use the REST architecture are called RESTful systems and they can be implemented in many ways, one of the most common being Web APIs.

REST does not enforce how to implement itself, but more so provides developers with guidelines and lets you implement it in your own way. However, there are constraints. All RESTful services are meant to implement the following:

  1. A Uniform Interface
    Using a Uniform Interface is fundamental to RESTful systems. It is the source of REST's simple decoupled architecture. There are four constrains for the Uniform Interface:
    Resource Identification in Requests means individual resources are identified in requests (such as using URIs in RESTful Web APIs). These resources could be HTML, XML or JSON, which are different from the servers internal representation.
    Resource Manipulation Through Representations which is when a client holds a representation of a resource (including any metadata), and it has enough information to modify or delete the resource.
    Self Descriptive Messages means each message includes enough information to describe how to process the message. And finally...
    Hypermedia as The Engine of Application State (HATEOAS) keeps the RESTful architecture unique from other application architectures. The server responds with text that includes hyperlinks which means there is no need for the client to be hard-coded with information about the structure of the application.
  2. Client–Server Separation
    By separating the client and server the developer is able to separate their concerns. For instance, by separating the interface concerns from the data storage concerns, you improve the ability to maintain the interface across multiple platforms. Moreover, it improves the scalability of the application by simplifying the server components.
  3. A Level of Statelessness
    The communication between the client and the server is not restricted to either of their states. This means that the server does not need to know anything about the state that the client is in or vice-versa. Every request from the client contains any and all of the information required to service the request.
  4. It should be Cacheable
    All API calls should be cacheable therefore responses need to define themselves are cacheable or at the very least not prevent clients from getting stale data in response to further requests. This helps tremendously with scalability and performance.
  5. Provide a Layered System
    To further assist with the separation of concerns, under normal circumstances a client should not tell whether it is connected directly to the end server, or to an intermediary along the way. A load balancer or proxy between the end server and the client should not affect communications. This will help with system scalability and by allowing additional layers to be added, provide greater security.
  6. And Optionally, Provide Code on Demand
    Optionally, you can provide code on demand. This simply means if you need to, you are free to return executable code to support your API. However, under most circumstances you will likely serve XML or JSON. The most important note here is to acknowledge that providing code on command is allowed when using REST.

Why and When Should I Use REST?

The why is simple; REST was designed with longevity in mind. It will be relevant for a long time to come and has become a web standard that most development teams are familiar with. It's scalable, reliable, and flexible. REST fits most projects as it is entirely independent from language or platform restrictions, meaning REST is compatible with most if not all projects.

If you're building an API, there's a very good chance you will want to consider the RESTful architecture. There are alternatives (discussed below), however it would be foolish to overlook REST. Not only is REST simple to build, but it also uses a relatively low amount of resources. Additionally, due to REST scaling horizontally so well, it's a prime choice for many projects.

However, REST is not perfect. It does come with it's own set of drawbacks such as oversharing, under-sharing which leads to requiring multiple requests/ responses to get specific data for your application. Consider the following, you are writing code to build a new Support Ticket application. You want to show a specific support ticket from a specific user. In order to get all of the information you need you may need information from the following routes:

/users/userId - To get the specific user information.
/tickets/ticketId - To get the specific ticket you want to display.
/comments/ticketId - To get the comments associated with the ticket.

Wouldn't it be more convenient if you could get all of this information form one Route? There are also situations where you may get more information than you want to display. Consider the same application but now you want to display a user account, so you use the following route /users/userId. Returned from the route is Json with the Username, User Timezone, User Location, etc... It all seems like useful information, but wait, why does the Json have a LastModified timestamp? That's not likely something you will need your users to see. Sure it's useful for the development or support team, but there are plenty of places where you won't need this information displayed.

Methods (Or Verbs)

REST uses verbs (or methods) in order to exchange data.

The following verbs exist:
GET - Fetches a record or set of resources from the server
POST - Creates a new set of resources or a resource
PUT - Updates or replaces the given record
DELETE - Deletes the given resource
PATCH - Modifies the given record
OPTIONS - Fetches all available REST operations

These verbs are actions that are performed on resources. A request is made to the client via http request with the verb, header information and optionally a body. You will receive a response back from the server, letting you know if the request was successful or a failure. 200, 201 and 204 status code responses are successful. 404 and 409 status code responses are failures.

Final Words

And that is REST in a Nutshell.