How to (and how not to) design REST APIs · stickfigure

Schnitzer with design suggestions for REST APIs. This is pretty straightforward, and I that it stays pretty simple and has a clear focus on usability.

1. DO use plural nouns for collections
2. DON'T add unnecessary path segments
3. DON'T add .json or other extensions to the url
4. DON'T return arrays as top level responses
5. DON'T return map structures
6. DO use strings for all identifiers
7. DO prefix your identifiers
8. DON'T use 404 to indicate "not found"
9. BE consistent
10. DO use a structured error format
11. DO provide idempotence mechanisms

Of all of them, I think 9 is one of the most important.