more info ⬇


subscribe for more
stuff like this:

SW engineering, engineering management and the business of software

2014 02 11

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:

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.

you may also be interested in some of the greatest hits of

〜 You Should Foster a Culture of Readability

〜 The Customer's Semi-Lucid Trance State

〜 ARC Best Practices

〜 Weighted Credit Pools for API Rate Limiting

the fine print:
© matt nunogawa 2010 - 2017
back ⬆