Coherence Daddy API

Provides interactive API documentation for the public endpoints exposed by the apex site, including rate limits, authentication requirements, request and response schemas, and code samples in curl, JavaScript, and Python.

Documentation follows OpenAPI 3.1 conventions. Each endpoint lists permitted methods, parameter constraints, expected status codes, and error response shapes. A 'try it' affordance executes calls against the production API with rate limits applied.

OpenAPI (formerly Swagger) is the de facto standard for REST API specification. Version 3.1, released in 2021, aligns with JSON Schema 2020-12, supports webhooks, and improves the schema composition syntax. The specification is a JSON or YAML document describing servers, paths, operations, parameters, request bodies, responses, and reusable components. Tooling around OpenAPI is extensive: documentation viewers (Swagger UI, Redoc, Stoplight Elements), code generators (openapi-generator, oapi-codegen), and testing tools (Schemathesis, Dredd) consume the same spec file.

The spec drives both the docs and the runtime. A handler-derived spec generation (used here) ensures the documentation always matches deployed behavior — adding a new endpoint or changing a parameter constraint propagates to the spec automatically without separate doc updates. The opposite pattern (hand-written spec, separate implementation) is fragile; spec drift produces docs that lie about actual behavior, which is worse than no docs at all.

A worked example. The /api/glossary/search endpoint accepts a query parameter q (string, required, max length 200), an optional limit parameter (integer, 1-100, default 10), and returns a JSON array of objects with shape {term, definition, score}. Status codes: 200 success, 400 invalid input, 429 rate limited. The OpenAPI fragment specifies all of this in a structure that both the docs UI and a TypeScript client generator can consume. A developer integrating the endpoint can copy a generated curl command, see the expected response shape, and verify their integration against the schema.

Authentication patterns vary by endpoint. Public read endpoints (search, glossary lookup) require no authentication and apply IP-based rate limits. Write endpoints and high-volume read endpoints accept API keys via Bearer authentication, raising rate limits for authenticated requests. The OpenAPI spec uses the securitySchemes component to declare each method; tooling renders the requirements in the docs and generates appropriate code for client libraries.

Limitations: the spec describes the API as it exists, not as it will exist. Deprecated endpoints remain in the spec marked deprecated=true, signaling clients to migrate but not enforcing the deadline. The 'try it' affordance executes against production, so calls have real effects (rate limits consumed, analytics counted). For destructive endpoints in any future API, a sandbox environment with separate base URL would be required; the current API is read-only enough that production execution is safe.