7 ms·
RESTful API Server - Doing it right
Tips on how to get your API server done right, especially when you are a startup.
- rauar 15y agoWe 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.
- icebraining 15y agoSorry, 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-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
- masklinn 15y agoAnd that's a clear case of not being able to downvote submissions being regrettable.
- nikcub 15y agonot to mention version numbers (a part of content negotiation) in user agents this isn't REST and only serves to confuse things further
- MugunthKumar 15y agoI agree. Updating my post on this. Thanks.
- tomstuart 15y agoI 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 15y agoI 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.
- deleted 15y ago[deleted]
- uxp 15y agoI 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 15y agoI 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).
- MugunthKumar 15y agoI haven't written anything about HATEOAS, caching and Internationalization intentionally as I'm reserving it for another post.
- arethuza 15y agoThat's a bit like writing an article on how to design boats and reserving mentioning water.
- MugunthKumar 15y agoI did mention that it's incomplete. It's impossible to write the complete thing in one post.
- brunoqc 15y agoAbout 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?
- valugi 15y agowhat's with the PHP hate?
- Terretta 15y agoBecause if you build your startup's site using PHP, you'll never be able to scale like a Flickr, Digg, Wikipedia, or Facebook. // Ahem.