Make authoring my own client in my own language straightforward. If you say "see our reference implementation in [some programming language I'm not using]" I'l

Make authoring my own client in my own language straightforward. If you say "see our reference implementation in [some programming language I'm not using]" I'll be very, very irate. This is the kind of thing I'm talking about: http://docs.recurly.com/recurlyjs/signatures/spec/ http://docs.recurly.com/recurlyjs/signatures/spec/. Expanding on that particularly egregious example: a handful of unit tests is not a specification, and if you want a variety of developers to use your API you can't have its documentation be a set of unit tests. A set of unit tests in a third-party DSL is even worse. Your documentation should be language agnostic. Everything should be described in regards to HTTP methods, not some aspect of your language, your language's standard library, or, god forbid, some third-party library in your language. If you DO expect users to rely on a reference implementation, it should be as generic as possible. I'm not a [insert language here] programmer and I don't want to have to learn the ins and outs of [your sandboxing tool] and [your library management tool] and [some fistfull of random third-party libraries] in order to install and run your samples. Always respond with the requested format, even on errors. Yes, I am advocating that you put a diaper (i.e. a try ... catch block that catches all errors) on your API endpoint. Diapers are generally a bad idea, but if I send you a json request that, for whatever reason, throws a server-side error, please return the error information in a json-parsable manner. django-piston is guilty of not returning json-parsable error pages, and it has the second-most followers of all bitbucker repositories. https://bitbucket.org/jespern/django-piston/wiki/Home https://bitbucket.org/jespern/django-piston/wiki/Home If possible, write sample clients on a variety of popular languages. Put your client on PyPi or RubyGems or npm or Pear or CPAN or whatever, just don't half-ass it. Know your audience. It's perfectly possible that your target audience doesn't actually give a shit about RESTfulness and they're perfectly happy using SOAP or (gasp!) XML-RPC. Those things may not be "cool" in the buzzwordy world of dynamic scripting languages, but the reality is that they're still standards and yes, people do use them. Be mindful of how insular HN is and where its interests lie; the HN userbase is representative of the HN userbase, not software developers as a whole. There's a creaking leviathan in the world of "enterprise" software whose foundation lies in things like Java and .NET and where mechanisms like SOAP and XML-RPC are still in use. SOAP is neither useless nor mandatory; it is used by a subset of the software development community, some of whom may be more than willing to give you good money to integrate with their services, if only you'd let them.