Yogesh Chauhan's Blog

A quick introduction to API, REST API and Postman

in Miscellaneous on May 12, 2020

What is API?

Wikipedia definition for API is: An application programming interface (API) is an interface or communication protocol between different parts of a computer program intended to simplify the implementation and maintenance of software.

๐Ÿ‘‰ In simple terms, An application program interface (API) is a set of protocols and rules for building software applications that specifies how different software parts should interact.

Even simpler terms…An API is just a bunch of code that allows two programs to communicate with each other.

An API may be for a web-based system, operating system, database system, computer hardware, or software library. Some popular APIs are Google Maps API, YouTube APIs, Twitter APIs etc.

How do they develop API? Do they share everything?

The answer is, obviously not. They use abstraction to show whatever is necessary and everything else is hidden.

In building software, an API simplifies programming by abstracting the underlying implementation, the basic structure.

It only exposing objects, functions and actions which the developer needs. For example, if you're building an API for an email service, you don't need to show how the overall email structure works to everyone that uses the API.

You can just simply provide a user with a button that performs all the steps for fetching and highlighting new emails.

In building an API for file input/output, just show a function that copies a file from one folder to another folder and not the overall file system operations that are occurring behind the scenes.

Advantages?

Creating APIs and exposing your data data with that API can improve the customer experience.How? Well, one simple argument is that using Google Maps API, many people are learning how the Google maps works and building even better applications using that API.

It's expanding Google maps actually and there are tons of examples like that.

What is REST API?

REST is acronym for REpresentational State Transfer.

It is architectural style for distributed hypermedia systems and was first presented by Roy Fielding in 2000.

Representational state transfer (REST) is a software architectural style that defines a set of constraints to be used for creating Web services.

What are RESTful Web services?

Web services that conform to the REST architectural style, called RESTful Web services. They provide interoperability between computer systems on the Internet.

REST and HTTP

While REST can be used over nearly any protocol, it usually takes advantage of HTTP when used for Web APIs.

๐Ÿ‘‰ This means that developers do not need to install libraries or additional software in order to take advantage of a REST API design.

It uses HTTP requests to GET, PUT, POST and DELETE data.

It is notable for its incredible layer of flexibility. Since data is not tied to methods and resources, REST has the ability to handle multiple types of calls, return different data formats and even change structurally with the correct implementation of hypermedia.

Main difference from SOAP?

Unlike SOAP, REST is not constrained to XML, but instead can return XML, JSON, YAML or any other format depending on what the client requests.

And unlike RPC, users aren’t required to know procedure names or specific parameters in a specific order.

How RESTful APIs work?

๐Ÿ‘‰ A RESTful API breaks down a transaction to create a series of small modules.

Each module addresses a particular underlying part of the transaction.

This modularity provides developers with a lot of flexibility, but it can be challenging for developers to design their REST API from scratch.

A RESTful API uses existing HTTP methodologies defined by the RFC 2616 protocol.

They use GET to retrieve a resource; PUT to change the state of or update a resource, which can be an object, file or block; POST to create that resource; and DELETE to remove it.

With REST, networked components are a resource the user requests access to — a black box whose implementation details are unclear.

All calls are stateless; nothing can be retained by the RESTful service between executions.

Creating a RESTful Web Service

A RESTful web service request contains 4 components which sitepoint explains really well.

1. An Endpoint URL: An application implementing a RESTful API will define one or more URL endpoints with a domain, port, path, and/or querystring — for example, https://domain/user/123?format=json.

2. The HTTP method: Differing HTTP methods can be used on any endpoint which map to application create, read, update, and delete (CRUD) operations:

HTTP method CRUD Action
GET read returns requested data
POST create creates a new record
PUT or PATCH update updates an existing record
DELETE delete deletes an existing record

3. HTTP headers. Information such as authentication tokens or cookies can be contained in the HTTP request header.

4. Body Data. Data is normally transmitted in the HTTP body in an identical way to HTML submissions or by sending a single JSON-encoded data string. 

For example,

a GET request to /user/ returns a list of registered users on a system,

a POST request to /user/123 creates a user with the ID 123 using the body data,

a PUT request to /user/123 updates user 123 with the body data,

a GET request to /user/123 returns the details of user 123,

a DELETE request to /user/123 deletes user 123

Other HTTP headers can be set including the Cache-Control or Expires directives to specify how long a response can be cached before it’s considered stale.

REST “Hello World” Example

We need to make sure that we have Node.js installed, then create a new folder named restapi.

A quick introduction to API, REST API and Postman

Create a new package.json file within that folder with the following content:

A quick introduction to API, REST API and Postman
A quick introduction to API, REST API and Postman

Run npm install from the command line to fetch the dependencies.

A quick introduction to API, REST API and Postman

Create an index.js file with the following code:

A quick introduction to API, REST API and Postman

If we launch the application from the command line using npm start and open http://localhost:8888/hello/ in a browser. The following JSON is displayed in response to the GET request:

A quick introduction to API, REST API and Postman

The API also allows a custom name, so http://localhost:8888/hello/everyone/ returns:

A quick introduction to API, REST API and Postman

What is Postman?

Postman is a popular API client that makes it easy for developers to create, share, test and document APIs. This is done by allowing users to create and save simple and complex HTTP/s requests, as well as read their responses.

Postman is a great tool when trying to dissect RESTful APIs made by others or test ones you have made yourself.

It offers a sleek user interface with which to make HTML requests, without the hassle of writing a bunch of code just to test an API's functionality.

An appropriate HTTP status code should also be set in the response header. 200 OK is most often used for successful requests, although 201 Created may also be returned when a record is created. Errors should return an appropriate code such as 400 Bad Request, 404 Not Found, 401 Unauthorized, and so on.

Simple REST Example with and without Postman

Let's open the following link in your browser to request a random programming joke:

https://official-joke-api.appspot.com/jokes/programming/random

We'll get output like this:

A quick introduction to API, REST API and Postman

That's just one array and one object we are getting in return. Imagine if we have an API that gives us many objects and arrays. Just like this API:

https://data.usajobs.gov/api/codelist/agencysubelements

A quick introduction to API, REST API and Postman

Postman makes it really easier to check the data from APIs. It has a great UI. Below is the screenshot of Postman.

A quick introduction to API, REST API and Postman

As we can see in the image above, all we need to do is add the api url and hit send.

There is an option to change the data format as well. Like JSON, XML, HTML etc. Like the following screenshot.

A quick introduction to API, REST API and Postman

That was only for GET request but Postman can run PUT, PATCH, DELETE, and various other request methods as well, and also has utilities to help with developing APIs.

Sources


Most Read

#1 How to check if radio button is checked or not using JavaScript? #2 Solution to “TypeError: ‘x’ is not iterable” in Angular 9 #3 How to add Read More Read Less Button using JavaScript? #4 How to uninstall Cocoapods from the Mac OS? #5 PHP Login System using PDO Part 1: Create User Registration Page #6 How to Use SQL MAX() Function with Dates?

Recently Posted

#Aug 15 Is PHP still good for back-end programming? #Aug 10 How to create a multisite network in WordPress? #Aug 3 How to create a circle that follows a cursor using JavaScript and CSS? #Aug 3 How to make a curtain slider using jQuery and CSS? #Aug 2 How to progressively load images and add a blurry placeholder? #Aug 1 How to create a placeholder loader (throbber) using CSS?
You might also like these
How to create a circle that follows a cursor using JavaScript and CSS?CSSHow to clean up after a plugin uninstall in WordPress?WordPressCasting in PostgreSQLPostgresThe difference between Class declarations and Class expressions in JavaScriptJavaScriptIs there a CSS parent selector?CSSWhen you donโ€™t want to @forward every member in SCSS (Sass)SCSS