Things you need to know before working with REST APIs

Many apps such as Facebook, Twitter, and Instagram are sending millions of requests per day and it all uses API. Here in this blog, will show you the different types of APIs and things that you need to know about, before working with API and some best practices.

What is API ?

API stands for Application Programming Interface. It serves as an interface that allows two applications to talk to each other. It enables the enterprises to innovate faster without actually getting into or understanding the actual code or software application. APIs are a set of rules, specifications, subroutines, and tools for building software applications.

API Interaction

API Structure

It is important to know the API structure. All websites uses protocols to connect with API such as https, smtp, etc… Followed by FQDN or IP, FQDN is again separated as host-name followed by dot and followed by second level domain with a dot followed by a top Level Domain. It is important to differentiate the APIs with version number for new releases with unique version number. Next thing is to identify the reference object pointing to that particular resource.

API Structure

API Documentation

API Documentation describes how API works and the types of services that API can offer. It is crucial to document an API in a well-defined and easy to read by others, which determines the success of your API. If a third-party application wants to integrate your API with their application by having clear, concise and easily understandable documentation can help developers save time instead of seeking help from support team.

Two most common API documentation and specification formats are RESTful API Modeling Language (RAML) and OpenAPI Specification.

SmartBear surveyed 3,000 API practitioners

Types of APIs

Types of APIs by availability

APIs By Usecases

APIs can be Operating System, Database System, Web-based System, Computer hardware, or software library.

Web APIs

Web APIs such as the Simple Object Access Protocol (SOAP), Remote Procedure Call (RPC), and Representational State Transfer (REST) is available in addition to program-centric APIs. Lets look into the REST API approach in details.

Representational State Transfer (REST)

REST is a software architectural style with six constraints for building applications that work over HTTP, often web services.

WebAPIs that comply with REST Architectural constraints are called as RESTfulAPIs. RESTAPI support formats, such as plain text, HTML, YAML, XML, and JSON. These APIs uses HTTP Methods to communicate to web servers.

HTTP Responses

HTTP defines a bunch of meaningful status codes which will be returned from your API. These are often used to assist the API users to route their responses accordingly. API users can identify the expected result with the desired HTTP response code returned from the server in their code.

Also see the full list of HTTP status code.

HTTP Methods

The most-commonly-used HTTP methods are POST, GET, PUT, PATCH, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations.

POST            Creates a new resource.
GET             Retrieves a resource.
PUT             Updates an existing resource.
DELETE          Deletes a resource.

POST Method

POST method is used to create a new resource, when the resource gets created should return a response code as 201 (Created) when it gets created in server

curl -d '{"id":10,"name":"Gold Winner"}' -H 'Content-Type: application/json' http://grocerystore.swagger.io/v1/oil

Also we can pass the file in json through data option as follows

curl -d @request.json -H "Content-Type: application/json" http://grocerystore.swagger.io/v1/oil

GET Method

GET method is used to read the resource which is already present in the server. Successful GET API request response code is 200 (OK) . In-case the requested resource is not found on the server then the response code would be 404 (NOT FOUND) .

curl -X GET "https://grocerystore.swagger.io/v1/oil/10" -H "accept: application/json"
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Thu, 15 Nov 2018 13:38:37 GMT
< Connection: keep-alive
< Content-Length: 20
<
{
  "id" : 10,
  "name" : "Gold Winner"
}

PUT Method

PUT method is similar to GET method but here we use PUT to update an resource which already exists. If updated resource is not present in the server then, new resource is created in server with response code 201 (Created) . If existing resource gets modified then 200 (OK) or 204 (No Content) response code is received on completion.

curl -d '{"id":10,"name":"Gold Winner"}' -H 'Content-Type: application/json' http://grocerystore.swagger.io/v1/oil

DELETE Method

DELETE method is used to delete resource which is identified by the Request URI. Successful deletion will return code 200 (OK) as response code. Delete operation is idempotent means, deleting a resource which is not present returns 404 (NOT FOUND) .

curl -X DELETE https://grocerystore.swagger.io/v2/oil/10

Examples of API

Google Maps APIs are integrated with most websites. Google’s Directions API uses an HTTP request to return XML or JSON-formatted directions between Geo-locations.

WeatherAPI is a geolocation and weather information provider with plenty of different APIs. JSON/XML RESTful API provides access to its geodata and weather.

Benefits of APIs

• Improved test coverage
• Increases Productivity
• Cost Effective
• Enhances customer experience

REFERENCES

Introduction

https://www.w3.org/Protocols/rfc2616/rfc2616.txt

https://www.geeksforgeeks.org/rest-api-architectural-constraints/