What is REST API

What is REST API

In this post, we will try to cover some of the basic questions around REST API  and one of the main questions is “What is REST API“?



REST is a short form of REpresentational State Transfer. Introduced by Roy Fielding, REST is an architecture style for distributed hypermedia systems. REST is not a standard but think of it as a set of constraints or principles which must be satisfied if we want to refer to an interface as RESTful.


1. Principles of REST

REST is a simple term can be called as a set of contains or principles which every interface must follow to be called as RESTful.


1.1 Stateless

Every request between client to server should have all the information needed to understand the given request and server is correct.A server should not store any client context between requests.This is one of the main principles of the REST design.


1.2 Client Server 

This constraint is added to have a separation of concern. By clearly defining client and server, we are separating user interface concerns (client) from the data/business process (Server). This design adds a lot of portability.


1.3 Cachable

Response data for a request should have a clear indication for cacheable or non-cachable data. If a data is marked as cacheable, the client has the flexibility to reuse this data for later use.


1.4 Resources

A resource is one of the fundamental concepts in REST API.A resource is a representation of anything that can be named e.g. image, a service, shopping cart, order, customer and so on.We can also think of the resource as an object having a type (e.g. ShoppinCart, Customer), data (e.g. ShoppingCart contain products) and maybe relation with another resource (e.g. ShoppingCart belong to a Customer).

RESTful API uses a resource identifier to identify a resource for a given interaction between client and server.Resource Representation indicated the state of the resource at a given time. Representation can have the following information

  1. Data for the resource.
  2. Metadata describing data in the given resource.
  3. hypermedia


With RESTful API, we have a resource if we have the URL, so /products/{productID} represents product resource for single product while /products is likely the address for collection of resources of products


1.5 Representations

Representation refers to the representation of the data objects and attributes (e.g in JSON or XML format). Let’s take a quick look at the customer resource representation

    "firstName": "David",
    "age": 35,
    "phone": "9111111111"


Above is a representation of the client resource.This is an example of the JSON format but this can vary based on your choice. Below is the list of known representation for the resource.

  • JSON
  • XML
  • YAML


2. REST and HTTP

This is one of the basic misunderstandings if you are starting with REST. REST and HTTP are not same. One of the main benefits of REST is to streamline web-based applications but this does not mean that any HTTP interface is a REST API.

To summarize

  • In a RESTful architecture, data and business functionalities are considered as resources.
  • These resources should be accessed using Uniform Resource Identifiers (URIs).
  •  Client and server will always exchange representation of resources (JSON or XML etc).

If you want more detailed answers to your question of “What is REST API ?” Please refer to following additional resources.

  1. How I Explained REST to My Wife
  2. steps toward the glory of REST
  3. RESTful Web Services
  4. Representational State Transfer (REST)


2. REST With Spring

Spring started supporting RESTful services with 3.0, here are some of the ways provided by Spring 3.x 

  • Use Spring MVC @RestController with ModelAndView
  • Use Message Converter


We will not cover ModelAndView approach as it is old an not suitable for the modern RESTful services. Spring 3.0 has the options to use annotation with HttpMessageConvertor which carry following advantages

  • Easy implementation with lightweight.
  • Minimal configurations.
  • Spring MVC provides multiple default settings for the RESTful APIs.


2.1 REST With Spring MVC 4.0

Spring 4.0 enhanced REST support by introducing @RestController annotation.With this annotation, you are no longer required to annotation all of our @RequestMapping methods with @ResponseBody.

@RestController Annotation combines @ResponseBody and @Controller annotation.If you are starting building your REST API, my recommendation is to use this annotation as it provides more ready to use REST API features, additionally, this provides a more meaningful name along with an option that it may carry additional semantics in future releases of the framework.



In this post, we discussed What is REST API and what are the principle if we want to design a REST API. We briefly discussed REST support in Spring Framework.In the next article, we will discuss the process of Building Restful Web Services with Spring 

This is an ongoing series on building REST API using Spring. If you are starting with REST, I highly recommend getting a clear understanding of the REST architecture before you dive into Spring with REST API guide.

In our next article of Building REST API using Spring, we will create Restful Web Services with Spring

Comments are closed.