REST resource naming checklist
· API Vertex reviewers
Before we annotate an OpenAPI file, we walk paths in pairs: what the domain expert calls the thing, and what appears in the URL. Mismatches here become breaking changes later.
Start with plural collection nouns
/permits not /permit for collections. Singleton sub-resources (e.g., /users/me) are exceptions we document explicitly in the report glossary.
Keep verbs out of paths unless they are domain events
Prefer POST /payments with a body over POST /createPayment. When the business sells “cancellation” as a distinct legal act, a sub-resource like POST /orders/{id}/cancellations can be justified in prose.
Limit nesting depth
We flag chains deeper than collection/item/subcollection unless the child cannot exist without the parent ID in every consumer story. Shallow URLs survive gateway rewrites better.
Align path segments with JSON property names
If the body uses vehicle_registration, the path should not say /cars/{plate} without a mapping table in the spec — integrators will guess wrong.
Document irregular plurals once
/people vs /persons — pick one, add a style guide appendix, and never mix within the same API major version.
Need a second pair of eyes on your draft? See our design review scope.