REST API Basics Overview.

In this article, I will touch on the basics of REST and Important concepts.

1. Introduction

What is REST?

REST stands for REpresentational State Transfer. It is an architectural style (not a protocol or a standard) that guides the design and development of the world wide web.

  • REpresentational – Formats(XML, JSON, YAML, HTML, etc).
  • State – Data.
  • Transfer – Carrying data between client and server.

REpresentational State Transfer

REST was originally created by computer scientist Roy Fielding, who was also the inventor of the HTTP protocol.

A REST API is an intermediary Application Programming Interface that conforms to the constraints of REST architectural style to enable two applications to communicate with each other over HTTP. In other words, API is a set of definitions and protocols for building and integrating application software.

The REST architectural style has quickly become very popular for designing and architecting applications that communicate with each other.

2. REST Key Concepts

Resource: Anything you want to expose to the outside world through the application.

URI – Uniform Resource Identifier: A resource is identified by a URI. For web-based systems, HTTP is the most commonly used protocol for communicating with external systems.

Sub-resource: Is a resource making part of a larger resource. For example, consider a Social media post (Resource) with many comments (sub-resource).

HTTP Methods: request-response protocol between client and server.

HTTP Status code: Message sent by the server to the client to indicate whether or not that request can be fulfilled. Common ones include;

  • 200 – OK: request successful – content returned to the client.
  • 201 – Created: request successful – new content created.
  • 400 – Bad Request: The server failed to process the request.
  • 401 – Unauthorized: Authentication is required for the resource.
  • 403 – Forbidden: Server refused to respond, even if the request is valid.
  • 404 – Not Found: Requested resource is not found in the location specified.
  • 500 – Internal Server Error: Unexpected error occurred on the server and the request cannot be fulfilled.

3. REST Characteristics

Client-Server Architecture: The client is the front end and the server is the back end. Both entities are independent of each other.

Stateless: No data should be stored on the server during the processing of the request transfer. The state of the session should be saved/handled at the client’s end. More

Cachable: The client should have the ability to store responses in a cache. Helps in improving performance.

Uniform Interface: Indicates a generic interface to manage all the interactions between client and server in a unified way. This helps in simplifying and decoupling the architecture. More

Layered System: The server can have multiple layers for implementation. The layered architecture helps improve scalability by enabling load balancing.

4. REST Architecture

The diagram below shows basic REST architecture


Communication between Client and Server

In the REST architecture, Clients send Requests to retrieve or modify resources, and servers send Responses to these requests. Below are standard ways to make requests and send responses.

Making Requests

A request generally consists of;

  • an HTTP Method (HTTP Verb), which defines what kind of operation to be performed.
  • a header, which allows the client to pass along information about the request.
  • a path to a resource.
  • an optional message body containing data.

It is the responsibility of the Consumer (Client application) to prepare and send HTTP requests.

HTTP Methods

There are 4 basic HTTP Verbs

  • GET – get a collection or a specific resource (by Id).
  • POST – create a new resource.
  • PUT – update an existing resource (by Id).
  • DELETE – delete a collection or a single resource.

Sending Responses

Content Types

When the server is sending a data payload (data or information that is returned by the server in response to a request) to the client, the server must include content-type in the header of the response. This content-type header field alerts the client to the type of data it is sending in the response body. 

Response Body

Responses from the server contain status codes to alert the client to information about the success of the operation. Refer to the Status codes section Above.

For each HTTP verb, there are expected status codes a server should return upon success:

  • GET – Return 200(OK).
  • POST – Return 201(CREATED).
  • PUT – Return 200(OK).
  • DELETE – return the most specific status code possible corresponding to the problem that was encountered. (refer to status codes)


Red Hat Blog