Agent WranglersResources and methods
Name resources as nouns, use each HTTP method for what it means, and answer with the status code that tells the client exactly what happened.
- Required 4
- Recommended 1
Required
Name resources as plural nouns
RequiredAddress each kind of thing as a plural noun, and each single thing by its ID under it. Keep verbs out of paths.
Use each method for what it means
RequiredRead with GET, create with POST, replace with PUT, change part with PATCH and remove with DELETE. GET and HEAD never change stored data.
Answer with the right status code
RequiredPick the status code that matches what happened. Never answer 200 with an error inside the body.
Keep addresses stable
RequiredNever change what an address means once clients use it. Add new addresses instead.
Recommended
Return 405 with the allowed methods
RecommendedWhen a path exists but the method doesn't apply, answer 405 and list what works in the
Allowheader.
For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/resources-and-methods.