For The-Data-Box, I had some hard choices to make because the API is the most exposed part to the community.
We could nearly summup like this :
- bad API = imminent death
- good API = involved community
But, what is a good API ?
I've been googling around to study some example of some popular API, like DropBox, Google Drive, GitHub, Stripes, FaceBook... and many others.
And I've found that API are mostly organized around REST, but they don't all respect the REST specifications.
Some of them simply don't use correctly the HTTP verbs (GET / POST / PUT / DELETE).
Some others don't follow the directive to *not* include the method in the URL, like "read" or "update" (because the command is supposed to be implicitly given by the HTTP verb).
Despite that, they are still good API, so, the strict respect of REST recommandations is not the only criteria to define what is a good API.
On top of this, note that the most popular API are not necessary the simplest to use... If you search for the keywords API + HEADACHE, you'll find this kind of interesting links :
http://blog.programmableweb.com/2011/08/11/survey-says-facebook-api-has-most-headaches-and-horror-stories/
From my point of view, the good API is the one that needs less time diving into the documentation's API, because people (mostly) don't like to read docs.
That's why I've decided to build a very "expressive" API, by *explicitely* telling what we are doing in the URL structure.
For exemple, following the REST recommandations, I should have used the same routes for POST / DELETE operations,
like this :
POST : https://api.the-data-box.com/v1/{SPACE_ID}/box-setups/{BOXSETUP_ID}
to update a box setup, and :
DELETE : https://api.the-data-box.com/v1/{SPACE_ID}/box-setups/{BOXSETUP_ID}
to delete a box setup.
Instead, I've chosen the longer and more
explicit URLs, telling both *the context* and the *operation* :
POST : https://api.the-data-box.com/v1/{SPACE_ID}/setup/boxes/{BOXSETUP_ID}/update
DELETE : https://api.the-data-box.com/v1/{SPACE_ID}/setup/boxes/{BOXSETUP_ID}/deleteIn the end, nothing is hidden by the protocol.
And that sounds better to me.
Of course, the API can evolve, this is not a big deal, and I could also build a version called "v1-strict", that would strictly follow the REST recommandations.
Only the future knows about that :-)
