| I thought I finally had REST figured out until I read this. Does anyone else see a diminishing return on pedantically following the REST-prescribed design and actually creating an API that people are familiar with out of the gate? I feel like if I followed this article to the T in my current design, anyone trying to integrate with it would spend so much time reading my API documentation just to figure out why they weren't getting an XML reply that it would stop being productive. I am working on an API for imgscalr right now and I think I have it about 80% RESTful at the moment -- the parts I'm not doing is paying any attention to the headers either coming or going between client or server. I'm using the more recent "classic" /path/object.{format}?arguments format that I have seen folks like Wordnik and Vimeo use. It may not be purely RESTful, but it is intuitive and I can't help but think: "Remember 3-4 years ago when REST wasn't all the craze and no one knew what it was? The web still managed to function back then..." I'm trying to mix some practicality in a bowl filled with "best practices" and come up with something that most people can stomach. I hope I hit that mark, but we'll see. As far as I'm concerned I'm sticking with the versioned URLs because I find it more intuitive for endpoints that change, get renamed or are removed than slamming one inside of a mime type or header or even a query string param a la AWS. |
the biggest issue with the rest-wanna-be interfaces is their use of object ids instead of object uris. so that I have to construct my own urls to access stuff.
in a proper restful api you are NEVER supposed to construct your own url. you are supposed to get all the relevant ones from the service.
and this kind of api is actually much more user friendly and allows for much better discovery. you just get the single top api url which has references for all the available collections objects and operations right there in the result.