The sentiment in the article looks laudable at first glance, but I have real trouble when the first paragraph ends with this:
> 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".
1) These are some hastily tossed off thoughts on a Sunday afternoon; not a manifesto. Quite happy to be taken to task on any of the points.
2) PHP is a perfect beginner language. Having tried everything from C, ASM, Java, Prolog, Java etc - I'd much rather play around in PHP. Ruby is similar - it's a well designed language with fairly little cruft - but I've limited experience in it.
3) As I say - most should be obvious. Yet most APIs aren't well designed.
4) Primarily, I'm looking at this from the POV of someone who spends a lot of time at hackdays. Yes, if you've got a week to learn the API, it doesn't really matter how your provide the API. But if you want people to get started quickly, provide as many languages and good libraries as possible.
5) You're probably right about the Wikipedia example. I think Apigee provides a nicer way of looking at a response.
Thanks for the link to Parse - looks interesting.
To reiterate - these aren't designed as a concrete example of best practice, just a way of looking at the problem which I don't think many people have considered.
Thanks for the comment - I may update the piece to reflect some of your very fair criticisms.
Try python - it would blow your mind.
For 7 years, I too was a PHP believer for its simplicity. It was my favorite language by far.
1.2 year ago, I started to use python and was hesitant with it at first. As I worked more and more in python, I simply fell in love it. It does lot of greats things that PHP does (dynamic arrays, dictionaries, and functional programming) and adds lot more functionality that PHP is missing.
1. How would you add a new element to an array?
PHP: array[] = 2
Python: array += [2]
2. How to combine 2 arrays?
PHP: ?? array_merge(...) ??
Python: array += array <- it is as simple as appending to a string.
I don't really agree although I don't really care either, but "simple" and "logical" it is not. In fact, all three rules I quoted from your text (and likely a bunch of others, those three just jumped at me) are repeatedly broken in PHP's standard library (and for no good reason besides historical).
> Ruby is similar - it's a well designed language
Ruby is not that well designed, but design-wise PHP is utter dreck. That is the issue I take with your introduction: PHP the language is not designed, is not logical and is not simple (although they've been trying to fix some of the most egregious issues in 5.x, 5.4 finally allowed `foo()[$index]` for instance); and PHP's standard library is a complete mess of inconsistencies and redundancies.
2) PHP is a perfect beginner language. Having tried everything from C, ASM, Java, Prolog, Java etc - I'd much rather play around in PHP. Ruby is similar - it's a well designed language with fairly little cruft - but I've limited experience in it.
PHP is good for a beginner because it has very little ceremony, an ALGOL-like syntax and a big standard library, but you can't say it doesn't carry cruft: it has a lot of bad decisions that can't be changed for backward compatibility, particularly the rampant inconsistency (both in the language and in the stdlib) and the kitchen sink of the global namespace.
I liked PHP until I learned Python. It's certainly not perfect, but at least it actually follow some rules.
> In many ways, PHP is that programming language. It’s simple, logical
I'll bite. From a UX perspective, PHP occupies the same important niche as WYSIWYG word processors or spreadsheets. Which is to say, optimized for beginners and quick websites. Even DHH has called it "absolutely perfect" [1] for small projects.
That's why I continue using PHP to whip up quick web apps, while reserving Rails or Node for heavier lifting. And I certainly wouldn't consider using PHP to do anything outside of a website, just like I wouldn't use Word or Excel beyond their own narrow scopes.
Also, the official PHP docs are substantially better than anything else. No weird 1997-style framesets, comments from other developers, and cool+predictable URIs (http://php.net/strlen).
> I'll bite. From a UX perspective, PHP occupies the same important niche as WYSIWYG word processors or spreadsheets. Which is to say, optimized for beginners and quick websites.
Sure, I have no issue with that, I have issues with the assertion that PHP is simple and logical. Neither the language nor the standard library are. I'd hope I would not have to demonstrate this on HN of all places.
I think you are looking purely at the language itself when what you need to look at is everything from getting started to actually seing it in reality in your browser.
I have a rule that says that if someone sings the praises of PHP then they are ignorant of all the other languages available as alternatives. If it's your first language, and you praise it, that's not so bad.
> 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/