When documenting a REST API you must create two main documentation areas:
- Reference documentation. It provides the actual API methods description, parameters definitions, error codes, usage examples and so on.
- Conceptual (or Non-reference) documentation. It provides context for the API. It explains what you can do with the API, high-level business goals, who the API is for, and other introductory information. Also, it contains getting started information which details the first steps to start using the API.
Another important aspect is to explain the API access policy. Before users can make requests with your API, they’ll usually need to register for some kind of application key or learn other ways to authenticate the requests.
Let’s see how to create a REST API documentation package using a fictitious web service. For more details, please refer to ManagePeople API.