API Publication Policy

This page defines how the project-owned HTTP API is documented and published for external users.

Scope

  • whatsapp-adapter-api owns the external REST contract and the raw OpenAPI source files.
  • Root docs/ owns the human-facing policy, auth guidance, and links describing that public API.
  • whatsapp-adapter-docs packages and publishes the canonical root docs site.
  • whatsapp-adapter-app may link to the published docs, but it is not the canonical publication surface.

Source Files

  • Use OpenAPI 3.1 for the public REST contract.
  • Store versioned public specs under whatsapp-adapter-api/openapi/.
  • Keep one source file per public major version, starting with whatsapp-adapter-api/openapi/v1.yaml.
  • Treat the YAML file as the handwritten source of truth. If JSON output is needed, generate it from YAML instead of maintaining two handwritten copies.
  • Keep explanatory pages in root docs/ and link them to the matching raw spec.

Publication Model

  • Publish the human-readable API documentation through whatsapp-adapter-docs.
  • Publish the raw openapi.yaml or generated openapi.json together with the docs site so users can inspect and import the contract directly.
  • If the operator UI needs to help users discover the API docs, add a link from whatsapp-adapter-app instead of duplicating the documentation there.
  • The operator-facing API reference page should render directly from the published raw spec, for example via docs/api-reference.md.

Versioning Rules

  • v1 is the first stable public major version.
  • Within a stable major version, allow additive changes only: new endpoints, new optional fields, and new optional query parameters.
  • Do not remove fields, rename fields, tighten validation, or change semantics in a stable major version.
  • Any breaking change requires a new major versioned contract file such as v2.yaml.
  • A new or changed endpoint is not treated as public until it appears in the matching versioned OpenAPI file.

Visibility Classes

  • Internal endpoints are not published in the public OpenAPI file.
  • Beta endpoints may be published only when they are explicitly tagged as beta in the spec and described as unstable in the docs.
  • Public endpoints must be present in the stable versioned spec and follow the compatibility rules for that major version.

Required OpenAPI Contents

  • Define the bearer-token security scheme explicitly.
  • Mark which operations require bearer auth and which, if any, are public.
  • For protected operations, document the expected 401 and 403 responses.
  • Give every operation a stable operationId, at least one tag, a short summary, and a description when behavior is not obvious.
  • Document request bodies, response bodies, validation constraints, and relevant error payloads.
  • Provide concrete request and response examples for externally consumed operations.
  • Keep vendor WAHA response details at the edge. The public spec should describe the project-owned request and response shapes.

Server URLs

  • Do not hardcode production hostnames in the spec before the final domains are assigned.
  • Until production hostnames exist, local examples may point to local development URLs only.
  • When production hostnames are assigned, record them in docs/remote-server.md and then update the published spec and docs links together.
  • Assigned production hostnames are not treated as ready until reverse proxy routing, certificates, and related publish settings are configured according to python-application-skill.
  • Treat public publication as incomplete until the final HTTPS hostname responds correctly with a hostname-matching certificate.