Versions

 

API Documentation

39) The API documentation (or ‘contract’) describes all aspects of the API in order to enable successful interaction between the API provider and API consumer. As such it should be a concise reference manual containing all the information required to work with the API, with details about the functions, classes, return types, and arguments. The API contract should, where relevant, be supported by tutorials and examples.
40) At a high level the fundamentals that need to be documented in the API contract in order for both parties to be able to interact are:
a. The business rules and service agreed between the API Providers and Consumers.
b. The rules around how each party authenticates themselves before gaining access to the API.
c. The standards that the API is adhering to including the change management and version control information that the consumer must be aware of.
d. The design of the API i.e. its structure, the resources (data) that it provides access to and how to interact with the API to obtain them.
e. The certification, on-boarding and acceptance of the API consumer from the API.
41) As such the API contract should also include the following content (but not be limited to):
•   sampling code and example responses
•   rules on information handling, incident management and risk management
•   method of authentication (and how it impacts service interoperability, single sign-on, and rate-limiting)
•   design changes (recent and planned) and versioning information
•   availability, latency, ownership, depreciation policies and status capability
•   approach to backwards compatibility
•   guidance on configuring the API to make sure any relevant governance frameworks are followed
•   the open data standards used
•   security information
•   cost of use of the APIs, if applicable
•   support that will be provided to the consumer of the API