Introduction To Restful Apis¶

REST(Representational state transfer) is a one of the architectural(designed with some specific rules and regulations) ways to transfer the data by using the HTTP protocol. In this article we will learn what are the restful api's and why we use it.we'll understand api request format and request methods in REST api's and it's usage.

Why we use REST API's ?¶

• It is mostly used with client server based applications. It's mostly used for Mobile application development(Android, iOS, etc), Client side web application development(ReactJS, AngularJS, BackBoneJS, etc).
• It transfers the data in the form of objects. The object is in the form of JSON. JSON usually is a better fit for data and parses much faster.

• REST follows a client server architecture.

• We use REST API's when there is a need of communication between multiple applications which were developed with different technologies(multiple programming languages like C, python, java, VB.NET, etc.)

• We can speed up the process by using cache mechanism in REST API's.

Understanding Request Format:¶

Before talking about the request methods first we need to understand the components of request. Every HTTP request is composed of two parts 1. Request Header and 2. Request Body.

1. Request Header:¶

   • Request Method: It contains the request methods like GET, POST, PUT, PATCH, DELETE, etc.

   • Request URI: It contains the information of domain and path.

     • Example: https://learnbatta.com/blog/
     • In the above example domain = "learnbatta.com" and path = "/blog/"

   • HTTP Headers: These are in the form of key and value. Find some of headers below

     • Accept: text/plain
     • Accept-Charset: utf-8
     • Accept-Encoding: gzip, deflate
     • Accept-Language: en-US
     • Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
     • Authorization: Token GfsgzxJUbjpvcGVuIHNlc2FtZQ==
     • Referer: https://learnbatta.com/

   • In Django REST Framework we frequently use "Authorization" header for authentication.

2. Request Body:¶

   • When we want to pass the data to the server securely then we use request body to send the data in request.
   • Request body is mostly used by POST, PUT, PATCH Request methods.
   • Note: In GET request method we pass the data in the url.

Example Request Format:

Host learnbatta.com

User-Agent Mozilla/5.0 (X11; Ubuntu; Linux) Gecko/20100101 Firefox/56.0

Accept text/html,application/xhtml+xm…plication/xml;q=0.9,/;q=0.8

Accept-Language en-US,en;q=0.5

Accept-Encoding gzip, deflate, br

Connection keep-alive

Upgrade-Insecure-Requests 1

Method GET

Body

Request methods in REST API's and it's usage:¶

• GET¶

  • We use get method to retrieve the information of a specific resource.
  • Resource will not be modified in the GET api request.
  • We can retrieve a single resource or multiple resources with pagination and filters by using GET api request.
  • Expected HTTP status code to the successful request is 200.
  • If requested resource was not found then we should return HTTP status code of 404.
  • If the GET request is not formed correctly as per api documentation then we supposed to return the error response with status code of 400.
  • Example urls for GET request
    • http://www.testdomain.com/users?offset=20&page=5
    • http://www.testdomain.com/users/1/detail

• POST¶

  • We use "POST" method to create the resource information in the database.
  • If resource successfully created then API should respond with HTTP status code of 201.
  • We need to validate the data before creating the resource information into the database. If the request data is not valid the server should return the errors data along with HTTP status code of 400.
  • POST method neither safe nor idempotent. Two identical POST requests may result in data duplication(i.e same data but different resource id's ).

• PUT¶

  • In general, we use request method "PUT" to updated the resource information in the database.
  • Resource will be modified upon successful completion of the request.
  • For successful "PUT" request API should respond with HTTP status code of 200.
  • It needs a resource Id to identify the correct resource to update.

• PATCH¶

  • We use request method "PATCH" to update the resource partially.
  • If resource successfully created then API should respond with HTTP status code of 200.
  • If resource is not found then API should respond with HTTP status code of 404.
  • It needs a resource Id to identify the correct resource to update it partially.

• DELETE¶

  • The request method name itself represents that "DELETE" is used to delete the resource on the server database.
  • When the resource "DELETE" request is processed successfully then it should return HTTP status code of 200.
  • If the resource is not found then API should return a HTTP status code of 404.
  • It needs a resource Id to identify the correct resource to delete it.

Summary of HTTP Methods for RESTful APIs¶

References:

1. https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html
2. https://en.wikipedia.org/wiki/List_of_HTTP_header_fields
3. http://www.django-rest-framework.org/api-guide/authentication/