

RESTful API Server - Doing it right - MugunthKumar
http://blog.mugunthkumar.com/articles/restful-api-server-doing-it-the-right-way-part-1/
Tips on how to get your API server done right, especially when you are a startup.
======
icebraining
Sorry, but it lacks the most misunderstood parts of REST:

\- Hypermedia as the Engine of Application State (HATEOAS)

\- Returning concrete mediatypes (standard is great, custom is OK) instead of
generic 'application/json' or 'application/xml'

It also contains some misunderstandings:

\- Sending a sha1 of the password to the server is bad, for two reasons:

\- - First, and more importantly, if you send the hash of the password over
the wire, the hash _becomes_ a plain-text password! Seems strange? Think about
it: if the attacker somehow gets the hash, he can just use it as-is to
authenticate to your API - he doesn't need to crack it.

If you're using HTTPS, just use Basic Auth. Otherwise, you should implement
(read: use a library!) proper request signing.

\- - Second, sha1 by itself is pitiful - it can be cracked in mere seconds.
Use bcrypt (this, on the server).

    
    
        Once you know the top level objects and actions in your product,
        designing the endpoints becomes easier and clearer. For example,
        to “add” a new venue, you would probably have to call a method
        similar to /venues/add
    

Sorry, but no, no.

In REST, there should be a _single_ endpoint. Everything else is done by
navigating.

And in REST, there are no method calls! As Roy Fielding would say, this
_screams_ RPC! To add a venue you should just POST to /venues/ (URL which you
discovered by navigating the API).

Read his blog post with some of the rules that make a REST API:
[http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

~~~
nikcub
not to mention version numbers (a part of content negotiation) in user agents

this isn't REST and only serves to confuse things further

~~~
MugunthKumar
I agree. Updating my post on this. Thanks.

------
tomstuart
I realise it's only part 1, but this post doesn't even mention hypermedia. Its
advice on documentation says that you should explain how clients construct
URIs. Groan.

I don't fully understand what it is about HATEOAS that people find difficult
or unconvincing. They must use web sites every day. When you want to buy a
book at Amazon, do you read their documentation and then construct a URL? No,
you go to amazon.com and click on shit.

~~~
arethuza
I must admit that the author's description of REST sounds awfully like what I
thought REST was before I sat down and tried to design a RESTful API. There
was a very distinct moment when I "got" the concept of only requiring a single
URL and then navigating the resulting documents - as you say exactly like a
web browser (which is, of course, the whole point).

It's clearly non-obvious to work with an API primarily as a set of documents
rather than as a set of "methods" to be called - I have no idea _why_ it's
non-obvious at the start as it is exactly how the Web works and it's pretty
obvious and elegant in retrospect.

~~~
uxp
I feel the same way. My first API on my current project was a horrible mess,
and did I only realize why it sucked and what I needed to change when I
decided to play with Backbone.js over a weekend using my API as a data source.
The only way, I think, one can build a RESTful API is to do it from the
client's perspective, much like BDD builds software using a list of actions
the user wants to make.

If you're not using your own API, then it's probably broken.

~~~
arethuza
I found that manually using my API from the command line using cURL helped a
lot (with a bit of cutting and pasting to extract the URLs I want).

------
rauar
We do I18N by providing a (cachable) name/value based dictionary using the
same REST API and return on error/validation the error source element and an
I18N error key. Makes rendering error messages a breeze as we name the input
elements by convention the same as the JSON property and therefore can easily
use that property in JQuery selectors.

------
brunoqc
About RESTful API, if you have many applications working together, do you
build an API and use it in every application or is the API only for
applications you don't control and you use the same code that you use for the
API in every application you control?

------
MugunthKumar
I haven't written anything about HATEOAS, caching and Internationalization
intentionally as I'm reserving it for another post.

~~~
arethuza
That's a bit like writing an article on how to design boats and reserving
mentioning water.

~~~
MugunthKumar
I did mention that it's incomplete. It's impossible to write the complete
thing in one post.

------
valugi
what's with the PHP hate?

~~~
Terretta
Because if you build your startup's site using PHP, you'll never be able to
scale like a Flickr, Digg, Wikipedia, or Facebook.

 _// Ahem._

