Every endpoint is described

Each REST endpoint says what it does, so callers and coding agents do not have to guess from the path.

MediumChecked automatically

Applies to:
Services with a REST API
Rule id:
api.endpoints-described

Why it matters

A path and a method are not a contract. POST /orders/{id}/cancel does not say whether cancelling a shipped order fails, refunds or is ignored. Callers who guess build on the guess, and a coding agent given only the path will invent the behavior.

How to apply it

  • Write one sentence per endpoint that states the outcome and the main rule: what changes, and when the call is refused.
  • Describe behavior, not implementation ("cancels the order if it has not shipped", not "updates the status column").
  • Keep the description in the design, so the generated OpenAPI file carries it.

Example

POST /v1/orders/{id}/cancel: "Cancels an order that has not shipped yet and releases its stock reservation. Returns 409 once the order has shipped."

References

Checklists with this rule

Related agent skill: sync-communication