> In many ways, PHP is that programming language. It’s simple, logical
and does not follow with "just kidding". Especially when the article itself contains things like:
> Keep your parameters consistent.
or
> What’s easier to remember “gnxID” or “getNextId”?
or
> Consistency is a virtue. If you have two similar APIs (say, search & read) they should take the same parameters and produce identically formatted responses.
Furthermore, while many of TFA's demands are the "well... duh" kind (though they do bear repeating), quite a few are also highly debatable:
> Just because you love Ruby, doesn’t mean everyone does. Show examples in a variety of languages.
Not sure why, as long as the examples are clear and readable (meaning Java is probably out as the only demo language), the language used for the examples should not matter. Stripe is awesome[0] but I don't think that thing should be termed as a requirement, let alone a "basic requirement".
> * Yes, you love XML. Guess what? I don’t!
> * The customer is always right. If the customer (developer) wants JSON, XML, PHPobject, or just plain text – you should give it to them.
> * It’s the API designer’s job to make life easy for developers – so reply in whatever formats the developer wants.
Is a second — significantly worse — iteration of the one above (and nonsensical in the face of the latter demand that the API developer provides libraries in a variety of languages: why do you care what the response format is if it's all hidden behind an access library exactly?). Are multiple response formats awesome? Sure. Are they a requirement? Fuck no, developers are not babies, as long as they have tools which let them process your responses (meaning ASN.1 is probably the wrong response format in most cases) they'll handle it just fine.
> The Wikipedia API is a brilliant example of this. They have a human readable response for their API calls.
The link leads to a dump of the XML response in an HTML page [1] in which lines are not wrapped and the non-text content of the response is a uniform and unreadable shade of blue. Meanwhile in every browser released in the last 15 years the original XML response [2] has syntax coloration, nicely wrapped lines and the ability to fold sub-trees you don't care about.
If [1] is brilliant, I'll do without brilliance thank you very much.
TFA's demands/recommendations are to be taken with a significant grain of salt: there's good, there's bad, and you'll have to pick them apart on your own.
While it does only cover documentary issues (which really are 30~50% of TFA) and not API design, I'd strongly recommend reading Parse's "Designing Great API Docs" instead[3], I find it comes across far better and... it documents what it preaches via examples for almost all its "bullet points".
[0] https://stripe.com/docs/api?lang=curl#top
[1] http://en.wikipedia.org/w/api.php?action=query&prop=lang...
[2] http://en.wikipedia.org/w/api.php?action=query&prop=lang...
[3] http://blog.parse.com/2012/01/11/designing-great-api-docs/