Join the DZone community and get the full member experience.
Join For Free
Build APIs from SQL and NoSQL or Salesforce data sources in seconds. Read the Creating REST APIs white paper, brought to you in partnership with CA Technologies.
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
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
The Integration Zone is brought to you in partnership with CA Technologies. Use CA Live API Creator to quickly create complete application backends, with secure APIs and robust application logic, in an easy to use interface.
Published at DZone with permission
Ajitesh Kumar, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.