more info ⬇


SW engineering, engineering management and the business of software

subscribe for more
stuff like this:

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

〜 Empathy as a Core Engineering Requirement

〜 Venture Capital Math 101

〜 You Should Foster a Culture of Readability

〜 The Customer's Semi-Lucid Trance State

〜 ARC Best Practices

the fine print:
© matt nunogawa 2010 - 2019 / all rights reserved
back ⬆