3 ms·

1. Documentation. It has been said in other comments. If you do nothing else right, do documentation. It is paramount. Documentation must contain code samples t

1. Documentation. It has been said in other comments. If you do nothing else right, do documentation. It is paramount. Documentation must contain code samples that can be ran without scaffolding a huge project. cURL command lines -- or the equivalent in non-HTTP APIs, are, for me, as good as it gets. 2. Account for failure. The failure path is more important than the-one-true-path. Be verbose in your errors. Be specific in your error descriptions. Be extensive in the kinds of error conditions you test, particularly when validating the input. Bonus points here if you can make the API introspectable. 3. Resource oriented. Expose your resources, then verbs on top of that. These are application-level resources. Do not directly expose the data model. RESTful APIs obviously follow this, but going REST is not the only option. 4. Stateless, or with as little state as possible. Stateless APIs make clients a lot simpler. They have the added bonus of scaling better on your end (on the server end). 5. Predictable. This is achieved by being both consistent and verbose. Do not use abbreviations on method names. Define a vocabulary and use always the same nouns to refer to the same entities. If using positional arguments, use the same calling order (i.e. avoid the needle/haystack you see in PHP).

ironcrucible 12y ago
> 2. Account for failure. The failure path is more important than the-one-true-path. Be verbose in your errors. Be specific in your error descriptions. Be extensive in the kinds of error conditions you test, particularly when validating the input. Bonus points here if you can make the API introspectable. This is something that I had to deal with just last week. I had been integrating a 3rd-party API into a business application, and it had very poor error handling and error descriptions. It wasn't even consistent on when an endpoint would throw an exception or just return some JSON with an error message. To make things worse, I kept running into the same generic error message: "Something went wrong. Please contact support at support@example.com if it continues". Of course, that kind of error message doesn't help their support team, so they could only guess as to what was going wrong. We finally figured it out after several hours of guessing. What's strange is that this was an API for a moderately popular Silicon Valley startup that's marketed to and primarily used by developers. Please, if you're building an API, don't write these generic messages!

ironcrucible 12y ago

> 2. Account for failure. The failure path is more important than the-one-true-path. Be verbose in your errors. Be specific in your error descriptions. Be extensive in the kinds of error conditions you test, particularly when validating the input. Bonus points here if you can make the API introspectable. This is something that I had to deal with just last week. I had been integrating a 3rd-party API into a business application, and it had very poor error handling and error descriptions. It wasn't even consistent on when an endpoint would throw an exception or just return some JSON with an error message. To make things worse, I kept running into the same generic error message: "Something went wrong. Please contact support at support@example.com if it continues". Of course, that kind of error message doesn't help their support team, so they could only guess as to what was going wrong. We finally figured it out after several hours of guessing. What's strange is that this was an API for a moderately popular Silicon Valley startup that's marketed to and primarily used by developers. Please, if you're building an API, don't write these generic messages!