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 documentation should start with a detailed description of what the API is about

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

The URL structure provided should include the following;


 * The base URI
 * The version of 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 version 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 requests 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. An example is given below;

''All responses to this API have a JSON response body with a  set to   on the response header. The structure of the body solely depends on the endpoint being queried.''

''All successful response will have an HTTP status code within the 2xx range, errors caused by the client will have a status code within the 4xx range, while errors caused by the server(such error are very rare) will have a status code within the 5xx range. There is also a type attribute sent with errors, which simplifies the error handling on the client-side with a human-readable error message attached.''

Errors
Different APIs respond to errors differently, consumers of your API must know which error to expect so it can be handled adequately.

Mediawiki API for example returns an error object with an error code and error message, you can read about it at API:Errors and warnings. As shown above, it gives code samples of what your error responses look like. Explain each fields of the response and what they mean especially the error types and status codes. This can be done in a table as shown below;

Error types
The above shows how the status codes and types should be displayed to audience, you could also have a look at API:Errors and warnings and API:REST API/Reference to see how errors are presented in Mediawki APIs.

Success
When a request is successful, the audience should have an idea of what the expected response looks like. Although this responses may vary from endpoint to endpoint, but it is expected that they are of similar structure.

A good example is shown below;

All successful request to this API would have a  parameter set to   and a   parameter containing the response object of that request as shown below;

Pagination
Some requests to certain endpoints have quite a lot of matching responses that are not returned on a single API call. You should explain in detail how the respnses to your API endpoints are paginated. Some APIs use the  and   query parameters, which gives the users full control over how much data they intend to query at a time, while sime simple automate this paginations. You should discuss in detail how pagination is handled on your API.

API endpoints
The audience of this documentation need to have a place where they could reference all enpoints this API provides, they need to know the following;


 * What is the body of the request of this endpoint.
 * What query paramters are necessary to add to this request.
 * What does the expected response look like.

Additionally, It would be really nice to take good advantage of the Special:ApiSandbox so the audience can test each endpoint on the fly without having to setup anything or write any code. The following gives a table of some of the Mediawiki Action API endpoints

NOTE: This is prefilled with mock responses and data. Some of the endpoints on the action API require authentiicated access. So this is just an example of how you could present endpoints to the audience. You don't necessari;y have to use this format.

Stewardship
Here, you would share useful information about the following;


 * Who maintains this page.
 * The project is written on.
 * How to contact the author and maintainers of this project(only share public information here, e.g zulip or IRC).
 * Links to discussion pages/threads.