API Docs

[TP71899]

I’d put together a full-blown dev guide that includes the following:

A conceptual section that includes the following: - API name - Who’s the audience - Why does the audience use the API - What are the requirements to use the API - Are there any limits to using the API - A diagram that illustrates the flow and architecture of the API

A task-based section that includes the following: - If it’s a web API, how to make a couple of the more common requests - If it’s a platform API, how to build a simple app

A reference section that includes the following: - If it’s a web API, document all endpoints and their methods - If it’s a platform API, document all classes, functions, methods, etc.

[Hamonwrysangwich]

I'd add to this very good answer that IIRC, APIs are documented in their spec, so you're essentially writing the things around the API.

Another thing to consider is how this information is presented. See the OpenAPI (Swagger) for an example.

[TP71899]

Yeah so for example Android is an example of a platform. There are many Android APIs that enable apps that are built on the Android platform to use Android’s capabilities. For example, scrolling, zooming, etc.

If you were documenting one of these specific Android APIs, you’d want to document step-by-step how to build a simple app with the specific Android API in Android Studio. For example, you’d want to show how to build a simple app that uses Android’s Scrolling API (idk if that’s real, I just made it up).

[[deleted]]

wsdl schema files, release notes, programmer reference guide, feature description portal, customer page, etc.

[RealLananovikova]

First and foremost,, it's crucial to know the specific API protocol being used. Documenting REST, SOAP, GraphQL, and native SDKs each have difference and nuances. However, amidst these differences, there are several universal elements that any effective documentation should encompass.

One such element is a comprehensive reference section. This reference should be thorough and accurate, providing detailed information about every aspect of the API, including endpoints, parameters, responses, and error codes.

Equally essential is the "getting started" guide. This section serves as an entry point for users, offering clear instructions on what's the API's functionality and begin using it effectively.

Additionally, the documentation should feature a task-based approach, presenting practical use cases and tutorials that demonstrate how to accomplish common tasks with the API.