Importance of Documentation on REST APIs
Khurshid Alam
Senior Technical Writer | Digital Content Strategist | Enabling users experience the software products in the easiest way.
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.
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
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 –
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
Base URL + Endpoint (query parameter + API Key)
onecall?lat={lat}&lon={lon}&exclude={part}&appid={API key}
Base URL: https://api.openweathermap.org/data/3.0/
Query Parameters:
Sample of query parameters
API Key: 01ed838d7d2dbfb0b46e84358b311f2d
Final request definition URL: https://api.openweathermap.org/data/3.0/onecall?lat=33.44&lon=-94.04&exclude=hourly,daily&appid=01ed838d7d2dbfb0b46e84358b311f2d
Validate the final request definition URL to confirm if it works and fetches the response.?
3 Send the request using a request method
API Request and Response in Postman
4 Define the Returned Response
5 Errors
Mention all the errors and why they occur.?
Note: This article was first published in Better Document.