Should an API documentation include When-to-use and when-not-to-use list?

1. What should API documentation include?
2. What should an ideal API documentation cover?
3. How do I write an API requirement document?

What should API documentation include?

API documentation should provide an example of every call, every parameter, and responses for each call. It should include code samples for commonly used languages such as Java, JavaScript, PHP, and Python. Documentation should provide an explanation for each API request and examples of error messages.

What should an ideal API documentation cover?

The foundation of your API documentation is a clear explanation of every call and parameter. As a bare minimum, you should describe in detail: what each call in your API does. each parameter and all of their possible values, including their types, formatting, rules, and whether or not they are required.

How do I write an API requirement document?

Understand and clearly articulate the detailed requirements for the API. Make sure there is agreement between key players before development starts. Separate functional from non-functional requirements and develop only to the functional requirements. Iterate through the API development process.