In This Tutorial, we will Learn About REST API, Web Services, Architecture of REST API, REST API Constraints and How to Test an API Using POSTMAN:
Pre-Requisites: Basic knowledge of Web Services.
Check here to get a clear understanding of Web Services.
Table of Contents:
What Is REST API?
API is simply an interface, which is used by software components to communicate with each other. A service is a function that is well-defined, self-contained and does not depend on any other services.
A Web Service is a type of API, almost all of them operate over HTTP. When a Web API is developed using REST Architecture then it is called REST Web API.
As of now, there are two types of Web Services,
- SOAP
- REST
Difference Between SOAP And REST
| SOAP | REST |
|---|---|
| It is a protocol | It is an architecture style and independent of any protocol, REST can use SOAP Web Services |
| It stands for Simple Object Access Protocol | It stands for Representational State Transfer |
| It uses service interfaces to expose business logic. | It uses URI to expose business logic. |
| SOAP has a strict standard to be followed. | There is no such strict standard mentioned, to be followed by REST. However, the user can follow few standards while developing web service using REST. |
| It requires more bandwidth. | It is lightweight. |
| It can define its own security. | REST inherits the security measures from the transport. |
| We can use only XML format to send the data in request body | We can have XML, JSON, etc. format for sending the request. |
| Best example is Google, AMAZON | Best example is YAHOO, LINKEDIN, AMAZON |
| SOAP uses HTTP, SMTP etc. protocol | REST rely on HTTP only. |
| The Rules for binding message, operations, etc is written in WSDL | REST follows WADL format for describing functionality offered by web services |
| It is standardized. | REST services are non-standardized. |
| It requires more learning time because of its existing rules, binding etc. | It requires less time to learn because of its simplicity. |
Why Choose REST Over SOAP?
Below points explain the reasons to opt for REST over SOAP.
- It is very good for developing and testing Web APIs.
- REST requires less bandwidth.
- We can use AJAX for the REST-based Web APIs.
- It requires lesser parsing overhead.
- The Payload size created by JSON is lesser in size.
There are many clients/tools available over the web, which enables us to consume RESTful Web services.
They are:
- Postman
- Advanced Rest Client
- DHC Rest client
- Requester
- Insomnia
- Assertible
- Poster
Why Postman?
- It displays all the available options.
- Postman has an additional feature (known as Runner).
- User-friendly UI and easy to use.
- Larger community group/members.
REST API Architecture
It is mainly the architecture of the Web in a software architectural style. It is for distributed hypermedia systems. A RESTful API directly takes advantage of HTTP methodologies defined by the RFC 2616 protocol.
Few definitions
API stands for Application Programming Interface. It is a set of subroutine definitions, protocols, and tools for building the application software.
Web Services are some program codes that contain data/inbuilt methods. These are deployed by the organization over the Internet to communicate with users, third-party applications, etc. For communicating the messages, mostly XML is used as a messaging system. XML simply encodes all the communications between users and applications.
HTTP means Hypertext Transfer Protocol, used by the World Wide Web. It defines how messages are formatted and transmitted, and what actions Web servers and browsers take in response to various commands.
Architectural style, these are characterized by the features which are used to create a structure and even make it unique. Styles are of two types: Layered and Uniform interface.
URI: Also known as a Uniform Resource Identifier. It identifies a resource (text document, image file, etc).
URL: Also known as a Uniform Resource Locator. It is a subset of the URIs, that includes a network location.
URN: Also known as Uniform Resource Name is a subset of URIs, that include a name within a given space, but no location.
For Example,
http://elearning.com/amazon/restapi.html#books
Here, in the above example
URI: http://elearning.com/amazon/restapi.html#posts
URL: http://elearning.com/amazon/restapi.html
URN: elearning.com/amazon/restapi.html#posts
Hence a URL is a URI that identifies a resource and also provides the means of locating the resource by describing the way to access it.
So every URL can be a URI but the reverse is not true.
A RESTful service is exposed through a Uniform Resource Locator (URL). This is a logical name that separates the identity of the resource from what is accepted or returned.
A sample REST Architecture:
REST API Constraints
An API interface is said to be RESTful if it fulfills the following constraints:
- Uniform Interface: It means, irrespective of any client we are using, the basic concept of implementing and using the REST services will remain the same. All the REST API’s developed should have a common approach to development.
- Stateless: This means no session to be stored. So, the server won’t be storing any HTTP Request sent by a client. Hence for a server, each and every HTTP request is a new request. No matter, how many times the request is made or the customer is the unique one or not.
- Cacheable: Caching means how frequent data and responses are being accessed from a cache instead of the server. The concept of caching is applicable while sending the client request. So the performance improvement is made on the client-side.
- Client-Server: Server and Clients are independent of each other in terms of implementation. A client only needs to send the request URI along with, or without authentication. Then the server takes the rest of the step, that is a response.
- Layered System: The client can send only the request to the server as resource URI. But then, before the request being sent to the server, there exists REST API, which provides us the layered system architecture. That means, we can have API deployed in one server, data is deployed in another server and authentication in another server.
- Code on Demand (optional): Sometimes a client may need more than just the response. REST API allows us to send an executable code as a response(this executable code can be a widget or any control). However, it is completely optional whether we have enabled/implemented this feature.
Few more terminologies related to Rest API:
Endpoint: It is the reference to a URL that accepts web requests. A web service is addressable using endpoint reference.
For Example, Http://{Domain_URL}//librarygr/libraries.xml
Resources: It is a subset of the Endpoint. Normally Endpoints expose some objects which can be consumed through web services. Resources are specifically that portion of an object over the Endpoint URI.
For Example, Http://{Domain_URL}//api/pg_library/ornithology/swan
Payload: Payload is the information that is sent while performing POST or PUT operation. These are the information specified in the body of the HTTP request.
Payloads are sent in JSON format, For Example,
{
Id: 1,
name:'sam',
phones:[{title:'mobile',number:9898989899},
{title:'home',number:8888888888}]
}
Parameters:
We can pass parameters in two ways.
Query Parameters: Useful to access key/value pairs in the query string of the URL (the part after the ?)
Best Example
http://jsonplaceholder.typicode.com/posts/?id=3
Path Parameters: It is useful to match a part of the URL as a parameter. We can send information as a path parameter in the following way: Form-data, x-www-form-urlencoded, raw, binary.
Best Example:
https://api.github.com/gists/49b05378bb8920d5b4ec54efc27103e2/comments
What Is POSTMAN?
POSTMAN is a REST Client, simply an app that comes with the Chrome browser. It is being developed, keeping developers in mind to make the API call testing easier. It has its own GUI for sending the API requests and reading API responses.
We can perform the REST API testing both manually as well as by automation.
In the following section, we will learn, how to test Web API manually using POSTMAN client.
How To Test API with Postman?
Installation
We need to access the Chrome Web store. In the Chrome browser search for Postman. Click here to add it to Chrome button.
Once it is successfully installed, we can find POSTMAN under the Chrome App. Just click the Postman icon to open POSTMAN. It will take time to launch for the first time.
Please refer to the following URL to understand how to use POSTMAN as a tool.
Pre-requisites: Internet connection is required to access services deployed over the web. In case of accessing the services deployed locally, make sure sufficient rights, privileges are given to the user who is executing test over POSTMAN.
Dummy Resource URI: In this tutorial, we will be using a dummy URI instead of a real URI. It will give us the responses as desired but changes cannot be made to the server.
http://jsonplaceholder.typicode.com
Navigation Steps:
#1) Once the POSTMAN App is launched, we can see the Request page by default.
#2) We can see the list of API calls by clicking on the drop-down. By selecting any of the options from the drop-down, we can request the API call to the server.
#3) Click on the Environment variable button at the top right corner of a POSTMAN. Set the specific Environment, where we are going to test. We can save it for future execution.
#4) The saved environment can be accessible from Environment drop-down.
#5) Next, we need to set the Resource URI in the given box.
#6) Click on the Params button next to the Resource URI field to specify query parameters
#7) Click on the Authorization tab, select the Authorization type from the drop-down and set any desired Authorization or, can simply leave it as No Authorization.
#8) Click on Headers tab and set the required headers like content-type
#9) Click on Body tab, select the form-data radio button. Specify required body parameters which need to be sent along with the request URL
#10) Click on Body tab, select x-www-form-urlencoded radio button. Specify required body parameters which need to be sent as encoded, along with the request URL
#11) Click on Body tab, select the ‘raw’ radio button. Specify required body parameters which need to be sent along with the request URL. This is in actual JSON format
#12) Click on Body tab, select the ‘binary’ radio button. Specify required body parameters(normally as a file) that needs to be sent along with the request URL.
#13) Once we configured all the details as specified above, we can now ‘Send’ the request. Also, we can save the send request as request.json(we may change the name of the request).
#14) We can see the list of Requests made, on the left-hand side panel under the History tab.
#15) Also, we can save all the details related to the Request(URI, Authorization, Parameters, body, etc.) under an existing Collection or a new Collection. Once the Request is added to the Collection, we can export(share) it and even can import any existing Collection.
We can share the Collection as a link, or as a team library by a simple generated code. We can always run the entire Collection suite.
Even we can publish the collection URL to the web so that anyone accessing the published URL can access the collection and consume the services provided by Web API.
There is a feature to log in to POSTMAN, which enables us to store the history, collections, environmental data, local storage so that we can save it and can access it anywhere, anytime after being logged in to the POSTMAN.
Runner
It is used to run the resources present in the Collections folder.
Conclusion
Most companies are adopting the REST architectural style for the development/implementation of web services because it is a simple and user-friendly interface, that requires less training for the existing/new members of the project. Organizations are considering REST along with their existing web services.
Also read =>> Flask API Tutorial
In the next tutorial this REST API series, we will discuss different types of response codes, types of REST requests, etc.