API Design is UI for Developers
shkspr.mobi
shkspr.mobi
> 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/
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.
T
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.
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.
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.
Lot more fun examples: http://python.net/~goodger/projects/pycon/2007/idiomatic/han...
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).
[1] http://david.heinemeierhansson.com/posts/23-the-immediacy-of...
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.
For a beginner PHP is simple and logical.
We'll have to agree to disagree, because that is not a statement I can accept.
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.
What language is easier?
Yes indeed, PHP is objectively a complete mess of inconsistencies piled atop hacks and seemingly random behaviors.
> What language is easier?
That is a very, very different issue than the original subject.
http://www.youtube.com/watch?v=aAb7hSCtvGw
If you're interested in the topic and haven't seen it yet, I urge you to do so ASAP.
All the resources are documented in the same way, it is nicely formatted, and easy to understand.
[0] http://blog.parse.com/2012/01/11/designing-great-api-docs/
It's a quick and dirty Ruby gem that exposes CSV data with RESTful endpoints (read-only for now) with a pretty docs page that automagically gives you:
1. Example code
2. Documentation for every single function
3. Human readable requests/responses
Automatic generation of client SDKs is a big TODO.
If you're still interested, check out http://github.com/adelevie/restivus.
Reading your docs.erb, the core structure (of the docs, and of the APIs it will document) seems to be along the lines of URL > Verbs > Content.
According to Fielding, you probably shouldn't call it REST or RESTful, because it's not[0]:
> A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
and
> A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].
That your documentation is function-driven:
> Documentation for every single function
also hints at this being RPC-over-HTTP more than REST (which is fine, as long as it's called correctly).
[0] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
I've seen many "RESTful" APIs with this structure:
GET / => index
GET /<id> => show
GET /?someparams=someattrs => filtered index
POST / (with encoded params) => create
PUT /<id> (with encoded params) => update
DELETE /<id> => delete
If you made a Rails scaffold, and got rid of any of the POST, PUT, and DELETE actions, and then added some basic filtering to GET "/", you would have a nearly identical API as generated and documented by Restivus.
Sure, just ask, I'll answer if I can.
> I've seen many "RESTful" APIs with this structure:
Yes, and that API is not even remotely RESTful according to Fielding (whom you may or may not agree with, but he's the guy who thought up REST and coined the acronym). It can be a fine API, but not RESTful: it's not hypertext-driven, instead it's a (hierarchically organized) set of function calls mapped onto HTTP.
> also hints at this being RPC-over-HTTP more than REST (which is fine, as long as it's called correctly).
In any context, documenting every function is good practice.
Masklinn was just stating that an API based on 'functions' is inherently not a REST API, but instead RPC. The documentation sentiment is sound, but your terminology was off.
If your API is procedural (is RPC), then yes, procedures being your core abstractions that's what you document.
But REST is not procedural, the core RESTful abstraction is the resource and it is that resource which provides state transitions from itself (to itself or to other resources). In HTTP these transitions are a triplet of (method, URI[, body]) but that's incidental.
Because the core abstraction of REST is the resource, resource types (or media types) is what you document, and the possible transitions from a media type are documented as part of that media type (more precisely, the media type's documentation indicates what the transition hookpoints are — for instance in HTML they're <link>, <a> and <form> — and what the semantics of those hookpoints are relative to the resource — if any).
To clarify, I have absolutely no issue with your goal of documenting your API and every endpoint of your API, I just take issue with your claim of documenting RESTful APIs when the very structure of your tool and production preclude any possibility of RESTfulness.
I think if you want to follow the "rule of least surprise" from the unix school of thought, this is probably a somewhat dangerous suggestion. Having one call go and do several things can make that call become something of a black box. It kind of breaks the rule of transparency as well. If I find myself having to do a dance with the API, as the end user there's nothing stopping me from writing my own helper code to group those common calls together; I'd prefer an API with total transparency and the least amount of surprise, which is ultimately more flexible.
Siiiigh. Here we go again, the C++ hate bandwagon. Let's see why he thinks this.
I was convinced that any 1st year student could design a better programming language.
That's normal for someone who doesn't yet have any idea what he's talking about.
One which behaved in a sane fashion without a lot of legacy cruft.
Okay, that's kind of vague...
In many ways, PHP is that programming language.
Nope. No, it isn't. Not at all. PHP is a mishmash of C-ish APIs that get things randomly backwards along with some handy built-in constructs. Also, it has some of the most appalling documentation of any mainstream language.
works without having to know lots of esoteric computer science.
I would love to know what "esoteric computer science" necessary to use C++, or any language for that matter. But that's not contained in this link-bait-y post.