REST API Best Practices

Use this skill when the main question is how to design, review, or improve a REST API — from URL structure to error formats to security.

Working Style

1. Start from what the consumer needs, not from what the database looks like.
2. Use HTTP as designed — methods, status codes, and headers carry meaning.
3. Express domain capabilities, not data operations.
4. Make errors as informative as successes.
5. Design for change: version early, break compatibility deliberately.

Design Workflow

1. Define the resources.
   • What are the concepts the consumer needs to interact with?
   • Name them with nouns, in plural form.
   • Use resource nouns; model a non-CRUD domain action as a task subresource when the contract calls for it.