SW engineering, engineering management and the business of software

subscribe for more
stuff like this:

Thoughts on API Design

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:

    • Everything is a GET
    • All of your HTTP response codes are 200s
    • Use of arbitrary error numbers
    • No MIME types

    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.



in lieu of comments, you should follow me on twitter at twitter/amattn and on twitch.tv at twitch.tv/amattn. I'm happy to chat about content here anytime.


the fine print:
aboutarchivetwittertwitchconsulting or speaking inquiries
© matt nunogawa 2010 - 2021 / all rights reserved