My current project is providing development support for a public-facing API product. It has been ongoing for two and a half years. In that time, we have transitioned from the speedy development of a brand new API toward steady-state development with a greater focus on supporting the product and improving the developer experience.
Here, I’ll walk through the different forms of public-facing API documentation and developer tools we added at different phases of the project.
OpenAPI Documentation
We documented the schema and behavior of our API using Swagger OpenAPI definitions from the start of the project.
We used this OpenAPI definition to identify operations exposed through our Azure API Management service and for validation of the API’s request/response handling using tools like Schemathesis for property-based testing. Because our OpenAPI definition had a real role in the testing and delivery of our API, there was a strong need to always keep this up to date and accurate.
Then, we use Redoc to generate documentation from our OpenAPI definition. This turns the request definitions, operation tagging, and code samples recorded from the start into standalone HTML documentation. Also rendered is markdown content inserted into the OpenAPI description. This included release notes, prerequisites guides, and support instructions. You can also download the original OpenAPI definition from this generated HTML page.
GitHub Issues
Once the API was officially published in a non-preview mode, there was a greater need to make bug reports/feature requests and their release schedules more visible.
To do so, we created a GitHub project where customers ask questions, report bugs, and track the status of their requests. This helps us track customer-reported bugs. It also documents limitations and known issues, since the development team itself filed many issues.
We also use this GitHub project as an informal method of documenting the release schedule. We try to keep issues up-to-date with status (in progress, implemented, scheduled for release vX.Y.Z, released, etc.).
Developer Portal
Next, with the goal of onboarding additional software integrators, we sought to improve the developer experience. We did this by building a custom developer portal. This portal included controls for setting up a new integration (generating accounts, API keys, etc.) and also acted as a collection of documentation.
Help Guides and Interactive Tutorials
A large chunk of the developer portal we built is simply several pages worth of rendered markdown content. This content documents intended usage of the API and explains key concepts, dependencies, and suggested development practices.
We then expanded on static markdown content with an interactive, step-by-step tutorial to help teach developers interested in using our platform about the intended use of the API. We simulate requests/responses, allowing developers to learn and experiment with the API without having to worry about setting developers up with accounts and API keys beforehand.
Future: Developer Tooling
As a future state, we have also considered expanding this developer portal to include downloads for various developer tools. Possible options represented in our backlog include adding Postman Collections, Node SDKs, and a starter React/Express project.
A Checklist for Documenting Your Public Facing API
Here is the complete list of the different methods we use to document our public-facing API:
- Changelogs and release notes to provide a historical view of new functionality
- Markdown content explaining key concepts and development considerations
- OpenAPI specifications to identify supported operations/explain behavior, and as a tool for generating types, performing validations, etc.
- Public issue tracker to document known issues, customer report bugs, and make release schedules more visible
- Developer tooling to improve developer experience and simplify the process of onboarding new software integrators