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.
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:
|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.
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.
Create a new package.json file within that folder with the following content:
Run npm install from the command line to fetch the dependencies.
Create an index.js file with the following code:
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:
The API also allows a custom name, so http://localhost:8888/hello/everyone/ returns:
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:
We'll get output like this:
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:
Postman makes it really easier to check the data from APIs. It has a great UI. Below is the screenshot of 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.
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.