Best OpenAPI Design

Treat an HTTP API as a long-lived resource protocol. Discover stable domain resources before defining routes, then preserve HTTP semantics through the OpenAPI contract, implementation, and verification.

Apply Authority In Order

Resolve design questions in this order:

1. obey applicable IETF HTTP RFC requirements;
2. preserve Fielding REST constraints, especially resource identification, representations, self-descriptive messages, and the uniform interface;
3. preserve compatible published contracts and explicit project-level policy;
4. apply this skill's baseline profile where the project has no conflicting requirement or established convention.