RESTful Web Services

What Does it Mean to Be a Restful Web Service

RESTful services are a service that follows a specific set of guidelines. Although not stated directly in the specification, it does make for great web services via HTTP requests. REST is short for Representational State Transfer and if implemented by following the below guidelines will help create a service which can be more easily consumed by other applications. You’ll often hear the term RESTful thrown around. There are 6 types of constraints or guidelines upon which a RESTful service ought to be built. There are developers who deviate from this, but in order for a service to be considered truly RESTful, it must adhere to the following 6 constraints. If you are really interested you can read

Roy Thomas Fielding’s dissertation on Representational State Transfer.  He was the one who developed the architecture and design pattern for RESTful services.

Uniform Interface

This is a way to allow for loose coupling of resources and is a fundamental part of good software development. There are typically four principle aspects to creating a uniform interface:

  1. Resources are identified by making a request, almost always using a URI (uniform resource identifier). For example http://myapi/resource/1. Following that the resources themselves can be returned in various formats (JSON, XML, etc) and the response is independent of the servers internal representation or model. If you are at all familiar with MVC patterns, this is often represented by the model and the object relational model as dispensed through a RESTful URI endpoint. I have almost always used JSON formatted responses, but the underlying idea is that your API should support multiple response formats. I know for example that ASP.net will send you a different response type based on the request header sent from the client.
  2. Ability to manipulate resources through there representations. In other words, after the client has received a response, it should be pretty clear by following a rest pattern how to modify or delete these resources.  For example http://myapi/resource/delete/1
  3. Each message from your API should indicate to the client how to best process the data, usually done through the MIME Type response, and allow reading of the data without the need for additional parsing or metadata.
  4. Clear communication should be established about what is allowable and what is not. No guessing about what your rest service should do. This is often identified by the naming convention of your URI’s and their endpoints. Another way to think about a Uniform Interface is that server responses announce available actions and resources. In other words, querying resources should allow the client to request other actions and resources without knowing them in advance. Take a look at this example below which comes from jsonapi.org

This response easily allows a developer to see what they are querying, the structure of the data, how to retrieve other data, and additional metadata about the API.

{
      "links": {
        "self": "http://example.com/articles",
        "next": "http://example.com/articles?page[offset]=2",
        "last": "http://example.com/articles?page[offset]=10"
      },
      "data": [{
        "type": "articles",
        "id": "1",
        "attributes": {
          "title": "JSON API paints my bikeshed!"
        },
        "relationships": {
          "author": {
            "links": {
              "self": "http://example.com/articles/1/relationships/author",
              "related": "http://example.com/articles/1/author"
            },
          },
          "comments": {
            "links": {
              "self": "http://example.com/articles/1/relationships/comments",
              "related": "http://example.com/articles/1/comments"
            }
          }
        },
        "links": {
          "self": "http://example.com/articles/1"
        }
      }]
    }

Client-Server

This is taking the separation of concerns and implementing loose coupling design patterns a step further. Think about a contract between services and that the business logic can change within either, but the data structure of the response from the URI’s will still maintain the same response pattern. This means that REST endpoints are the same as well as the data structure returned. If you’ve ever worked in a situation where the rest service changed and the client application breaks you understand what this means. Basically, you can have the underlying code change for how the service works, but the way to interact with it and the representational model of your data is still structured in the same way. Otherwise, the contract between applications is broken and they are no longer able to communicate effectively. The client maintains it’s own state of data representation and best if implemented without having the server maintain the client state.

Stateless

This basically means that if a client has the privileges to view a resource, the resource is open and visible and that the server maintains no client state. Think of it as a continuation of the loose coupling of applications. Sure there is a security layer involved, but that is not the responsibility of the REST API, nor is it the responsibility of the REST api to keep track of when a client last requested certain resources. If there is a level of application state that needs to be maintained, say for security purposes that is up to the client to maintain those details and usually sends that piece of authentication detail with the request. You may be familiar with local storage and use of JSON Web Tokens (JWT tokens), this is one example where client maintains state, another would be in the use of a session cookie, which allows the client to access certain resources.

Cacheable

This one can require thought, especially if there is a resource which is being accessed regularly by the client-side application. Think about ways in which you can cache certain resources, as this will greatly reduce server-side interactions and load upon those resources. As we’ve said, the RESTful API is supposed to be stateless, so if an application is constantly accessing the same resource, think of ways in which to cache those details. Most modern web frameworks use a certain level of abstraction and make this much more manageable, especially for something like updating a resource through a form, or object manipulation for performing a post or update to resources. Caching should be applied also to those resources which declare themselves cacheable in their metadata. This is also part of the REST service design and architecture.

Layered System

This basically means that through the use of a RESTful API, you can scale more greatly and keep in the spirit of loose coupling of resources, not just code. For example, you can keep you datastores on a separate machine than the machine with the API, as well as intermediaries along the way. Think about using something like Docker for containerizing applications and scaling instances behind a load balancer as well. This type of architecture can greatly increase the ability to scale and keep performance for large enterprise applications where it should be.

Code on Demand (Optional)

As stated this part of the RESTful implementation is quite optional. I’ve actually not implemented this aspect myself, but where I have seen it is when calling a REST API for JavaScript code, that is then used to run another process on the client. Examples I’ve seen are when using google maps API and disseminating street views. I’d call there rest endpoint usually passing in some coordinates and return the JavaScript needed to build the street-view on the client side in an <iframe> for example. For the most part, though you will return static resources or update a resource.

To Summarize

I hope you found this useful and will share. I hope you also noticed that the specification does not specifically call out the HTTP methods which are commonly associated with REST API’s but are almost always used. For some additional information regarding that checkout

spring.io’s page. Gives a great summary of GET, POST,  PUT, DELETE and PATCH, as well as HTTP status codes. I think that you’ll find there is a lot in creating a truly RESTful API, and I hope I’ve helped to dispell some of the myths as well. It really is flexible and if implemented correctly is essential to building and maintaining quality software.  

Next On FoC

Git Using the Command Line

Git Using the Command Line
Previously On FoC

Write A Blog For Your Career

Write A Blog For Your Career