I’ve spent the better part of the last year designing and implementing APIs.
In that time, I’ve recently come across two very good articles:
Principles of good RESTful API Design
Probably the best overview of best practices on API design I’ve come across. Somehow the author has managed to be thorough, yet succinct.
Signs you’re veering from good API design
Four very good anti-patterns:
The item about error numbers leaves me conflicted, however, as they are invaluable during development and can help narrow down errors to specific points in code.
Lastly, something I struggle with is making the API secure vs making it easy to use. You need a balance here. Oauth is so developer-hostile. I personally recommend a scheme similar to Amazon’s S3 service, as well as making everything run over https. One of the primary downsides of https (difficulty caching) doesn’t typically apply to API endpoints.
With respect to error codes, 4XX errors (the API consumer messed up), good error messages are important. Ideally, there should be enough information to help the consumer resolve the issue on their own. One security related message worth mentioning is that it is considered a better practice to combine username/password errors into one generic “Username and/or password is incorrect” type message rather than a separate message for username not found and incorrect passwords.
5XX (the server messed up) error messages should be vague as possible. Too much detail can actually expose you to attacks. I tend to use error numbers for traceability, but no error messages beyond the generic 500 Internal Server Error. If malicious parties are prodding at your API looking for vectors, you are better off treating them like mushrooms: in the dark.