RESTFul API

An API is an Application-Programmer Interface essentially a set of functions, objects, and methods that are made publicly known to developers that allow them to interact with a particular technology. APIs are useful because they enable programmers to utilize the capabilities of different technologies without needing to know their internal implementation.

Example: You can use the Google map API to enable whatever application you're writing to search geographical locations. As a programmer, you don't need to know anything about how google wrote google map or how it works under the hood. With the API google map provides (set of methods, functions, etc.) you can utilize its capabilities anyway.

REST (Representational State Transfer) is an architecture style for designing networked applications. REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP, WSDL, et al.). The World Wide Web itself, based on HTTP, can be viewed as an REST-based architecture. The entire modern web browsers are REST client. RESTful applications use HTTP methods (GET, POST, PUT, and DELETE) to perform CRUD operations

Advantages:

• Simple
• Easy to use/implement
• Easy to build
• Uniform interface
• The REST API is always independent of the type of platform or languages
• Visible, reliable, and scalable

Most of the people answer about the pages which uses the REST apis, lets see the real time example. REST is something the clients (browsers) and servers can interact in complex ways without the client knowing anything beforehand about the server and the resources it hosts. Whereas the client and the server must be in sync with the server about the media they are using for the API. To go deeper let me quote an example. In a signup form if we have age parameter and the server accepts it has only integer, if the client send that as an string then the server will throw an error since it cant be an string since the server has set that parameter as integer. Assume your mom requesting you to buy some thing from a shop. Here mom is client and you are the server. http://home.com/buyThings?item=s... . This is a common REST request it can be from your father or mother. You anyway process the data (since you are a server) and you get the things done and give success response.

The API is an interface, through which many developers interact with the data. A good designed API is always very easy to use and makes the developer’s life very smooth. API is the GUI for developers, if it is confusing or not verbose, then the developer will start finding the alternatives or stop using it. Developers’ experience is the most important metric to measure the quality of the APIs.

The most important terms related to REST APIs

• Resource is an object or representation of something, which has some associated data with it and there can be set of methods to operate on it. E.g. Animals, schools and employees are resources and delete, add, updateare the operations to be performed on these resources.
• Collections are set of resources, e.g Companies is the collection of Company resource.
• URL (Uniform Resource Locator) is a path through which a resource can be located and some actions can be performed on it.

The resource should always be plural in the API endpoint and if we want to access one instance of the resource, we can always pass the id in the URL.

• method GET path /companies should get the list of all companies
• method GET path /companies/3 should get the detail of company 3
• method DELETE path /companies/3 should delete company 3

In few other use cases, if we have resources under a resource, e.g Employees of a Company, then few of the sample API endpoints would be:

• GET /companies/3/employees should get the list of all employees from company 3
• GET /companies/3/employees/45 should get the details of employee 45, which belongs to company 3
• DELETE /companies/3/employees/45 should delete employee 45, which belongs to company 3
• POST /companies should create a new company and return the details of the new company created

Isn’t the APIs are now more precise and consistent.The paths should contain the plural form of resources and the HTTP method should define the kind of action to be performed on the resource.

When your APIs are being consumed by the world, upgrading the APIs with some breaking change would also lead to breaking the existing products or services using your APIs. http://api.yourservice.com/v1/companies/34/employees is a good example, which has the version number of the API in the path. If there is any major breaking update, we can name the new set of APIs as v2 or v1.x.x