Tips on how to get your API server done right, especially when you are a startup.
RESTful API Server - Doing it right
blog.mugunthkumar.com
RESTful API Server - Doing it right
1–10 of 33 posts
Re: RESTful API Server - Doing it right
#2We 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.
Re: RESTful API Server - Doing it right
#3Sorry, 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
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...
Re: RESTful API Server - Doing it right
#4I 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.
Re: RESTful API Server - Doing it right
#5Sorry, 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 passw…
And that's a clear case of not being able to downvote submissions being regrettable.
Re: RESTful API Server - Doing it right
#6I 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 an…
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.
Re: RESTful API Server - Doing it right
#7I 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 an…
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…
[deleted]
Re: RESTful API Server - Doing it right
#8I haven't written anything about HATEOAS, caching and Internationalization intentionally as I'm reserving it for another post.
Re: RESTful API Server - Doing it right
#9I haven't written anything about HATEOAS, caching and Internationalization intentionally as I'm reserving it for another post.
That's a bit like writing an article on how to design boats and reserving mentioning water.
Re: RESTful API Server - Doing it right
#10Sorry, 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 passw…
not to mention version numbers (a part of content negotiation) in user agents
this isn't REST and only serves to confuse things further