m API-Writing / API-Documentation: API Template

Tuesday, April 22, 2008

API Template

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

10 Comments:

At 4:21 AM, Blogger SEO Expert India said...

I came across this world best learning center, www.lindamoodbell.com - delivers awesome training to improve efficiency in reading, writing, communication, dyslexia, hyperlexia, autism for those child who suffer from this.

improving reading comprehension

autism instruction

treatment for dyslexia

spelling help

improving reading

More Information:

http://www.lindamoodbell.com/

http://inforequest.lblp.com/

 
At 2:40 AM, Blogger Content/Technical Writers said...

I think API writing or writing for APIs requires some technical knowledge also as its difficult for a person write about anything that he/she is not aware of. Are there any formal training given for API writing?

 
At 6:19 AM, Blogger Research Writer said...

Many institutions limit access to their online information. Making this information available will be an asset to all.
Custom Papers Writing

 
At 4:14 AM, Blogger resumedocket said...

Many thanks for taking the time to discuss this, I really feel strongly about it and adore learning far more on this topic. If possible, as you gain expertise, would you mind updating your weblog with more details? It can be really very helpful for me.

 
At 11:48 PM, Blogger karina said...

Excellent sharing Thanks for share i am sure its must help me. thanks for doing this.
Software Product Development

 
At 11:30 PM, Blogger nhnndfkfd said...

Thanks for API telplate... I was searching such type of template on internet and i found it here

Work in New Zealand

 
At 6:29 PM, Blogger - said...

Latest News Updates Bollywood, Hollywood, Dating & Fashion
Online Bollywood News and Reviews
http://www.onlinebollywood.net/

 
At 8:43 AM, Blogger sebastian said...

simple blueprint for github API readme file:
https://github.com/naked/hive-go/blob/master/API.md
via google plus

 
At 8:44 AM, Blogger sebastian said...

simple blueprint for github API readme file:
https://github.com/naked/hive-go/blob/master/API.md
via google plus

 
At 9:31 PM, Blogger SJeem Ahmed said...

Job Portals became out standing platform on internet for performing sourcing now a days mostly employers as well as employee performing continuous activity there hiring and finding Jobs in Middle East Countries, Dubai, PAKISTAN, Etc is became easy after invention of job portals its became easy solution for both employee as well as employer. Posting Jobs and creating CV for applying on posted jobs posted by employer its just few step's away.

 

Post a Comment

<< Home