Documentation/API Documentation Template

= API Documentation = This document provides a simple template that can be used as a starting point for technical documentation that is intended to guide the audience through the use of REST APIs.

Who should use this template?
This template is suitable for writing any form of REST API documentation and is limited to just that. Writing any other form of API documentation is well beyond the scope of this template.

= Template = Below is the provided template for this particular genre and is to be duly followed when creating documentation.

Overview
API documentations should start with a detailed description of what the API is about

URL Structure
Often, REST API's have a basic URL strcture for requests made to any of their endpoints. Since no interraction can be made with an API without the URL, it becomes important to explicitly state the structure of URL before moving on to any other aspect of the documentation.

The URL structure provided should include the following;


 * The base URI
 * The version if the API has versions
 * The endpoint

An example of the above put together is shown below;

Versioning
Some APIs have evolved over time and therefore have different versions, each versions of APIs are quite distinct and some are not backward compatible.

The versions of the API should be explicitly stated as well as appropriate revisions.

Request format
Querying data over an API requires making some sort of requests and sending some payload or data with that request. How requests should be made to you API shuld be clearly defined here.

Request headers
Some request need certain headers to be sent as a part of the request. Most often, the two headers that are sent are the Methods, Content-Type, and Authorization headers.

The specific headers that might be needed to access some endpoints should be stated here and why that header may be required.

Clearly state all Methods that are allowed. The most common ones are GET, POST, PUT, and DELETE.

You should also state if some endpoints require some sort of Authorizations before access is provided.

Authentications
Some endpoints are protected and need authorized access, you shoud explain how you athenticate endpoints here and hw authenticated requests should be made.

Additionally, code samples i the appropriate language or CURL should be added here so the audience can get a better understanding of the explnation provided.

Response Format
People who consume an API need to have an understanding of what kind of data is returned from an API and how the data is structured. The response gotten from an API when a request is successful is quite different from the response gotten when the request fails. Both success and error responses should be explained in detail.