API stands for Application Programming Interface, a way for two or more computer programs to communicate with each other. Using APIs, we can transcend the traditional challenges of data sharing and connectivity between software built on different and often incompatible platforms and technologies.
APIs are everywhere, and though we may not be aware, we use them every day. Some of the instances where APIs are used in the background:
- Posting a photo from Facebook to Instagram.
- Tracking your food order delivery.
- Checking the weather forecast.
APIs have been around for a while. The past decade has witnessed a surge in API development and usage. As per ProgrammableWeb, a well-known public API directory, the year 2022 saw over 24,000 APIs being listed with them. The graph below shows the massive growth in their directory volume since 2005:
In a 2022 Postman survey, 51% of respondents said that more than half of their organisation’s development effort was spent on APIs. In 2021, developers sent over 1.13 billion API requests using Postman (Postman is a platform for building and testing APIs).
The pandemic has further accelerated the need for API usage, as many businesses have been forced to undergo digital transformation to stay competitive.
Why is API Documentation Essential
For any software, documentation is essential for user education and adoption. Given below are some reasons that stress the importance of good API documentation:
- Developers are the primary consumers of APIs and need comprehensive, accurate, and well-structured information to start. Not just content, it is vital to provide a great user experience to developers. It is quite simple really – if the experience is not great, why would anybody want to use it? Hence, good documentation and user experience are critical for API success!
- API documentation leads to a reduction in support costs. By adding error descriptions, troubleshooting, and FAQ sections in the documentation, we can ensure that developers are able to find answers to questions without approaching support.
- API documentation is an important resource for internal teams and new employees to learn about a particular API and how it works.
Who Does It
Engineers maintain API documentation
A few organisations prefer to make API documentation part of their code base. This means that developers write the code and document it. Any changes to the code are immediately reflected in the API documentation as well, making it easy to maintain. This works if the organisation’s Engineering team is willing to maintain large chunks of code along with descriptive documentation. At times, documentation takes a back seat and becomes outdated.
Tech Writers documenting APIs
Many organisations prefer their Tech Writers to update and document the API documentation. A Tech Writer is empathetic to user needs and an expert who spends a lot of time documenting each and every nuance of an API with easy descriptions, ample examples, and sample codes. All that is needed is the right coordination between Engineering and Tech Writing to ensure clean and well-maintained API documentation.
Open API Specifications
If you have created your APIs in line with the Open API specifications (a standard interface description for HTTP APIs), you can also try and automate API documentation using tools such as SwaggerHub, Postman, apiDoc, Stoplight, and so on. Engineers or Tech Writers – anybody can use this tool to document APIs. This is an automated process, which is efficient but may require final touches from a Tech Writer to ensure that complete descriptions and adequate examples are added to make your APIs easy to fire.
Test Before Documenting It
Tech Writers usually receive the API details from the Product Managers and Tech team in the specifications document. As it goes with agile development, the software changes; hence, the developed version is different from the planned version. Therefore, Tech Writers should test the APIs at their end to ensure that they capture the correct information in the documentation. Postman, SoapUI, and Apigee are some of the tools used in the industry to test APIs.
At Razorpay, Tech Writers perform API testing using Postman.
Anatomy of API Documentation
Ideally, API documentation should contain the following sections:
- Introduction: An overview of the API and authentication instructions.
- Use cases: A brief explanation of the different goals the developer can achieve using that particular API. Given below is an example of how we have provided the use case for Orders API.
- Entity explanation: A list of all the parameters used in the API, along with their descriptions.API Endpoint:
- List the API endpoint.
- Provide the sample codes in all supported languages to cater to the needs of a wide community. At Razorpay, we provide sample codes in 6 server languages.
- Detailed parameter descriptions with additional information such as data type, supported character length, whether they are mandatory/optional, and so on.
- Errors: Add the error response along with the reason and the suggested next steps.
- FAQs: List of questions that may arise during the API integration.
While the above-mentioned sections are mandatory, the following enhance developer experience:
- Best Practices: Some specific rules may need to be followed to get the best results from certain APIs. Those can be listed separately.
- Invest in an API Explorer: An API explorer is an excellent way of providing developers with a means to try out the API before the actual integration. Adyen has an excellent API explorer.
API Documentation at Razorpay
Razorpay offers APIs for easy integration of the Razorpay Payment Gateway, RazorpayX, and other Razorpay offerings like Payment Links, QR Codes, Subscriptions, Route, and Smart Collect.
Developer Experience is critical, and hence API documentation takes center stage. We are constantly working towards improving the overall API experience with better documentation. We undertook the following initiatives:
- New API document structure based on user research and feedback, market trends, and best practices in the industry. For example, we added a section on API basics since a segment of our users are non-developers.
- Comprehensive and up-to-date API documentation- Updated code samples and request parameters.
- User Feedback on the Docs site to make continuous improvement on Docs. For example, added use cases, better parameter descriptions, and more examples.
- Sample Codes in 6 Server Languages. Sample codes in more languages had been a constant ask from the developers. We worked with our Engineering team and added sample codes in PHP, Python, Java, Go, NodeJS and Ruby.
- Adding error codes for all APIs. Developers need to know how to handle both success and failure scenarios, and hence it is important to provide error responses, along with the suggested next steps. We are working with the integration team to list out the possible error responses.
- Razorpay Postman Public Workspace. A Postman Public Workspace is akin to a repository for API sample codes. Postman users from anywhere in the world can access the Workspace, create a copy of the sample codes, save them to their private Workspaces (using a process called Forking), and test them at their leisure. We went live with the Razorpay Postman Workspace last year and have seen good traction with 4278 forks and 3483 watchers. In fact, Razorpay was one of the 15 top workspaces in terms of fork numbers, as per the Postman report! Check our blog about Razorpay Postman Public Workspace: https://razorpay.com/blog/simplifying-your-api-experience-launching-razorpay-public-postman-workspace/
Source: Postman Report
The Tech Writing team at Razorpay works closely with the Tech and Integrations team on these initiatives as they are the subject-matter experts and have extensive experience working knowledge of APIs. Essentially, this gives us an opportunity to get direct feedback from the users who refer to API documentation and are the target audience.
APIs are here to stay. If your organisation uses a lot of APIs and you still do not have a structure to document APIs, it’s time to add it to your to-do list. It is absolutely critical to put in efforts to create excellent API documentation to boost the adoption of APIs. We hope this article has helped you with some pointers and provided a framework for documenting your APIs. Take a shot!