Software developers send request for a service to API database, interpret the returned response, use the data

Application Programming Interface or API is a piece of software programming code for a function or service. Native APIs have been with the software development since very beginning. However, REST APIs have been gaining importance among the SaaS companies or those who want to use third party APIs.

Why third-party APIs?

Third-party APIs are required for a number of reasons.

Site Speed: If you write the programming codes for all functions in your web pages, your site will become too heavy and will take time to load. In the last twenty years, site speed has been a very important factor to engage users visiting a site. If a site takes longer to load, the bounce rate would be high and users would leave the site with bad impression.

APIs are a format of the programing codes used as a reference point in the website, so the length of inline coding is reduced. Secondly, the codes do not need to run unless they are required. For example, on a banking website, there may be a calculator tool to estimate loan, interest, and EMIs but the customers visiting the banking website do not need to use this if they do not need any loan. This means they do not run the API for EMI calculator. There may be several tools in the same way.

Third-party APIs: There are hundreds of tools and services for different functions such as calendar for writing date of birth with date, month, and year; country code directory for writing country names, states, cities, zip/pin numbers. It is advisable to use such tools than redeveloping them if you need them for your website.

Public Organizations: There are government organizations or popular international organizations that have accurate and reliable data in certain fields such as medical fields, weather conditions, or public services. To fetch live and accurate data, you need APIs from such organizations. For example, to show report on weather condition, you may need data from https://openweathermap.org/.

Where Documentation Fits for APIs?

Documentation is the user interface for APIs. In one of the surveys, the software programmers responded accurate documentation as one of the top 3 requirements.

Source: https://www.youtube.com/watch?v=Ew3_sdRcEA0

This is because when you are using third-party APIs, you may not be familiar with the convention of the APIs and there may be hundreds of APIs with similar service names.

What are the Components of API Documentation?

Some of the important components of API documentation include.

Service name
Request definition
Request method
Response Interpretation
Error codes

Service name

Explain the service name clearly, keeping one thing in mind how it is different from others. For example, there may be several APIs on weather conditions like daily status, forecast, monthly status.

Write service names like –

Weather – Nowcast (Current weather condition)
Weather – Forecast (Weather condition in next 24 hours)
Weather – Forecast (Minute basis)
Weather – Forecast (Hourly basis)
Weather – Alerts (Normal)
Weather – Alerts (Alarm)

Request definition

Base URL: Define the base URL and the endpoints distinctively. Use colors to differentiate them.

Example: Base URL + endpoint (query parameters + API Key)

Mention required parameters: Different ‘Request definitions’ may require different parameters. Make sure you include all the required parameters with description.

Request method

Mention the CRUD (Create, Read, Update, Delete) operations like POST, GET, PUT, PATCH, Delete to indicate what impact the service request inherits.

Example:

Get

https://spponacular-recipe-food-nutrition-v1.p.mashape.com/recipes/convert

Response Interpretation

Define all the parameters in the returned response in simple language to make the parameters useable for coding by the coders and engineers.

Error codes

Mention all possible errors

Sample of an API Documentation

Picked up an API Call from OpenWeather: https://openweathermap.org/

1 Service Name of API Call

API Call to Send a Request to Fetch Weather of a Day

2 Creating Request Definition

Call Request: Base URL + Endpoint (parameters + API Key)

Base URL:

https://api.openweathermap.org/data/3.0/

Query Parameters:

Abbreviation	Full form	Value	Description
lat	latitude	33.44	Brief description
lon	Longitude	-94.04	Brief description
Exclude	Exclude parameters if not required	Hourly,daily	Brief description
appid	API key	01ed838d7d2dbfb0b46e84358b311f2d	—