Categories: API DevelopmentEnterprise Architecture

API Tips – How to Write API Documentation

This article represents tips on how to write documentation for APIs which are going to be published to developers, both internal and external. It touches upon some of the important areas/points that needed to be included in API documentation such that developers find it easy enough to work with APIs. Please feel free to comment/suggest if I missed to mention one or more important points. Also, sorry for the typos.

3 Areas to Cover while doing API Documentation

Landing page which provides details such as high level information of APIs, links to APIs pages, release information, changelog details
A summary page providing an overview on APIs in general, list of API names and one liner for each of the APIs
One page each for each of the APIs where following details could be included:
- API Description providing details on some of the following:
  - Functional details including information on what API accomplishes
  - API syntax including method signature and request, response parameters
  - Request and response parameters such as parameters’ description, data type, mandatory or optional information
  - Exception details including error codes, what do they mean and how to handle them.
- One or more code examples which could be used by developers when integrating with APIs
- Related APIs which are used along with this API or which provide greater details in relation with functioning of the API
- References, if any, to get further details about APIs

Author
Recent Posts

Ajitesh Kumar

I have been recently working in the area of Data analytics including Data Science and Machine Learning / Deep Learning. I am also passionate about different technologies including programming languages such as Java/JEE, Javascript, Python, R, Julia, etc, and technologies such as Blockchain, mobile computing, cloud-native technologies, application security, cloud computing platforms, big data, etc. I would love to connect with you on Linkedin.
Check out my latest book titled as First Principles Thinking: Building winning products using first principles thinking.

Latest posts by Ajitesh Kumar (see all)

Agentic Reasoning Design Patterns in AI: Examples - October 18, 2024
LLMs for Adaptive Learning & Personalized Education - October 8, 2024
Sparse Mixture of Experts (MoE) Models: Examples - October 6, 2024

Ajitesh Kumar

I have been recently working in the area of Data analytics including Data Science and Machine Learning / Deep Learning. I am also passionate about different technologies including programming languages such as Java/JEE, Javascript, Python, R, Julia, etc, and technologies such as Blockchain, mobile computing, cloud-native technologies, application security, cloud computing platforms, big data, etc. I would love to connect with you on Linkedin. Check out my latest book titled as First Principles Thinking: Building winning products using first principles thinking.