# API reference page template with request and error examples

Canonical: https://githtml.com/guides/api-reference-page-template
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

An API reference page should let a reader understand one operation without inferring hidden defaults. State the method, path, authentication requirements, parameters, response fields, and meaningful errors. Keep illustrative examples separate from guaranteed behavior, and verify the page against the API contract and implementation revision it describes.

## Define the contract before the example

Begin with the operation's purpose and the audience allowed to use it. State which inputs are required, where they appear, accepted formats, and the meaning of an omitted value. For every response field, explain units, nullability, and whether clients should tolerate unknown fields according to your actual contract. OpenAPI provides a standard vocabulary for describing HTTP APIs; use the project's chosen specification version rather than assuming the newest one applies. A reference page should not quietly expand permissions or invent a behavior absent from the underlying service.

## Show success and failure as different cases

An illustrative export-status endpoint could accept an export identifier and return pending, complete, or failed. Describe what each state means and when a download reference exists. Then show an unknown identifier and an unauthorized request as separate cases using placeholder values. Make clear that the example is fictional. If the service adopts RFC 9457 problem details, document the fields it actually returns rather than copying a generic object and implying support. Keep tokens and real customer identifiers out of both examples and screenshots.

1. Identify parameter location, type, required status, and constraints.
2. Explain response fields in words, including timestamps and measurement units.
3. Document the error a client must handle, not merely a successful response.

## Review examples like executable claims

Compare examples with the checked-in contract and relevant tests. If an example was tested, record the environment and revision; if it was not, label it illustrative. Avoid presenting a request as harmless merely because it appears in documentation: requests may create resources or disclose data. Prefer readable escaped code blocks in the HTML output. A reader such as gitHtml displays the committed reference, while authentication and actual requests belong to the user's separate tools. Put compatibility notes near the operation so readers do not miss them in a distant release appendix.

## Sources and further reading

- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457.html)

## Related guides

- [Architecture decision record template with review triggers](https://githtml.com/guides/architecture-decision-record-template)
- [Operational runbook template with safe stop conditions](https://githtml.com/guides/operational-runbook-template)
- [Developer onboarding guide template for a first useful change](https://githtml.com/guides/developer-onboarding-guide-template)
- [Software migration plan template with exit and rollback gates](https://githtml.com/guides/software-migration-plan-template)

Editorial approach: https://githtml.com/guides/about