Woodridge Tech Talk

Our ongoing series of bi-weekly technical presentations

REST and HTTP Verbs

REST (and a little bit about verbs)

The term REST comes up frequently in discussions about architectures and APIs. Although it has a precise definition, there are people who misuse the term. There are some who focus on just particular aspects of the REST architecture style, and others who use REST as no more than a buzzword. In this blog post, we’re going to look at how REST is defined to clarify what the term actually refers to. We will also take a look at HTTP verbs to clarify how to use them properly.

What is REST?

REST is a type of architecture for Distributed Information Systems, defined by R.T. Fielding in 2000. It is defined by 5 mandatory constraints on the architecture:

  • Client-Server

    The UI on the client end is separate from the data storage on the server end. Doing this improves scalability by simplifying components on the server, allows components to evolve independently, and allows the UI to be used across multiple platforms

  • Stateless

    Information about the user’s session is managed by the client. Requests to the server cannot rely upon any context stored on the server – all information needed to understand the request must be in the request. Doing this improves visibility by not requiring further requests to understand the request, improves reliability by making it easier to recover from partial failures, and improves scalability since the server does not need to track states between each request. However, this also requires more requests with repetitive data.

  • Cache Management

    All data sent in responses from the server to the client must state (implicitly or explicitly) whether the data is cacheable. Equivalent requests will reuse the cached data. Doing this increases efficiency and scalability by reducing redundant requests, and increases user-perceived performance by decreasing latency. But, this can cause some issues if the cached data differs significantly from data on the server

  • Uniform Interface

    Components in the architecture use common interfaces, regardless of how the provided service is implemented (what comes in and goes out is the same, how the component does this is irrelevant). Doing this allows independent evolution of components but lowers efficiency, since the form of responses is standardized instead of optimized to the application’s needs.

  • Layered System

    The system may have multiple layers, but components only know about the layer they are interacting with. Doing this allows us to have multiple providers of different services and for legacy services to still be used. However, it also reduces user-perceived performance as the multiple layers increase latency.

There is also an additional, but optional, constraint that deals with the transfer of scripts/applets from the server to the client. The full details of the REST architecture style can found here.

Without these five constraints, architecture is not truly RESTful, but may still be REST-like. And that’s fine. Each constraint has advantages and disadvantages, and it’s important to evaluate which constraints are beneficial and necessary for your particular architecture.

HTTP Verbs

Many resources online focus on the proper use of HTTP Verbs and URI naming when talking about REST. Although the proper use of HTTP verbs and your URI conventions don’t define a REST architecture, they can assist in its implementation.

  • Get ← [safe] Use for fetching resources
  • PUT ← [idempotent] Create/Update resource
  • POST ← Create/Update resource
  • DELETE ← [idempotent] Delete Resources

There are two important terms here.

  • Safe: The use of the verb implies that the request will make no changes on the server.
  • Idempotent: Sending the same request multiple times will have the same result.

There are many opinions on when to use POST versus PUT. Some developers avoid PUT altogether and simple use GET and POST for all requests. Ultimately, the developer decides which HTTP verbs will be used for which requests, and which ones will be used at all. Regardless of what the verb’s intended use is, the developer can always ignore this with their server-side code (although I would not recommend it). If we want to stick to standards, however, HTTP/1.1 standards describe the difference between POST and PUT as such:

“The fundamental difference between the POST and PUT methods is highlighted by the different intent for the enclosed representation. The target resource in a POST request is intended to handle the enclosed representation according to the resource’s own semantics, whereas the enclosed representation in a PUT request is defined as replacing the state of the target resource. Hence, the intent of PUT is idempotent and visible to intermediaries, even though the exact effect is only known by the origin server.

Proper interpretation of a PUT request presumes that the user agent knows which target resource is desired. A service that selects a proper URI on behalf of the client, after receiving a state-changing request, SHOULD be implemented using the POST method rather than PUT. If the origin server will not make the requested PUT state change to the target resource and instead wishes to have it applied to a different resource, such as when the resource has been moved to a different URI, then the origin server MUST send an appropriate 3xx (Redirection) response; the user agent MAY then make its own decision regarding whether or not to redirect the request.”

So, if we are modifying a specific thing and know the URI, use PUT. But, if we need the backend to determine where changes need to be made, use POST. In other words: if modifying the resource does not affect anything else, use PUT.

So, if we are modifying a specific thing and know the URI, use PUT. But, if we need the backend to determine where changes need to be made, use POST. In other words: if modifying the resource does not affect anything else, use PUT.

Closing Remarks

After taking a detailed look into what REST is, it should be easier to identify systems that are RESTful and those which are not. However, it is important to not judge a system just based upon its RESTfulness. Take into consideration what your system needs to do – and determine if a fully RESTful system is actually needed. Your architecture might not be 100% RESTful, but it may still be the ideal solution for your scenario.

Categories: Tech Talk