API Template

An API Template must include the following:

• Syntax: Syntax (prototype) of API
• Description: Detailed description of the API
• Parameters (input, output): Details of all the input and output parameters along with description of values that can be passed.
• Return Value(s): Details of the values returned by API after execution.

API template may also include all / any of the following:

• Synopsis: One line description of the API
• Calling Sequence: The order in which an API must be called
• Usage Scenario: Expected scenarios where the API can be used
• Examples: Most of the programmers makes best use of this place and are expert in copying the examples provided illustrating the use of APIs.
• Related APIs: Information on the APIs that could be related to the API being documented
  Class / Object/ Method name: Name of class / object / method associated with API
• Data types: Any special data type declared only for specific API
• Header File: Any header file associated with API
• Parent class: Details of any parent class associated with API
• Exceptions / Error Messages: Any exceptions or errors that a user may encounter while using the API
• Notes/Warnings: Special notes or warnings while using the API
• Associations or dependencies (if any)

Sample API Template- Here is the sample API Template for C/C++ language:

• API name [Write API name here]
• Synopsis [Provide brief description of the API]
• Include(s) [Provide name of header files to be included.]
• Library / Libraries [Provide name of associated libraries]
• Syntax / Prototype [Detailed Syntax of API, here example of C++]
  int function(
  int param1,
  char* parma2,
  int* param3)
• Description [Provide detailed description of the API along with exceptions (if any)]
• Argument(s) [Provide the details of parameters/ arguments]
  param1 - param1 description, by default an input parameter
  param2 [out] – param2 description, output parameter
  param3 [in/out] - param3 description, both input and output parameter
• Return Values
  ret1 Description of return value
  err1 Description of error (Error is also a return value)
• Calling Sequence - Provide the flow chart or sequence in which the API should be called, mention if there is any dependency.
• Usage Scenario - Provide the usage scenario (details on how to use and when to use this API) of the API and possible error or success conditions and how to tackle those errors.
• Example
  Example Statement
  Example code
• See Also / Related APIs
  API1 (along with cross reference)
  API2

http://coloredwritings.blogspot.com/2007/05/api-session-with-rajeev-jain.html