Someone (bradgessler) in HN made a very good comment in this thread.
I’m just going to copy-paste everything. Source.
The biggest problem with today’s REST implementations is that they’re essentially a database serialization layer. Consider how a RESTful Rails model is typically represented as:
{ book: { id:1, name:"To Kill a Mocking Bird", author_id:2 } }
How do you get more info on the author if you only have this piece of information? Rails/ActiveResource guesses through convention: “/authors/2″, but that might not be the case, which makes this approach very brittle.
A better more “RESTful” approach might be:
{ book: { href:"/books/1", name:"To Kill a Mocking Bird", author: { href:"/authors/2" } } }
The REST client would then be able to traverse the representation without making guesses at the URL, and if the end-point of ‘/authors:id’ changes for whatever reason, the href would be updated accordingly.
Pagination/large data-sets could be solved as well:
{ books: [ href:"/books/1", name:"To Kill a Mocking Bird", author: { href:"/authors/2" } } ], rel: { prev: "/books?page=1", next:"/books?page=3" } }
… and a bajillion other common RESTful API problems through better convention.
I’d agree with the author that REST is misunderstood, but my opinion is that its misunderstood on the grounds that today’s “REST” implementations are lame database serializations. The web has been doing this since the <a href/> tag was conceived, but for some reason, modern REST implementations left this out.
Is it good to change the key on this from books to book every time?
I like the approach! I think it would be time consuming to write a service that is always looking at a different entry point for the same endpoint /books/1 or /books
Thoughts?
It’s all thanks for bradgessler from Hacker News
For the entry point you were talking about, I think it would be a matter of preference. But on the top of my head, I do not see why not…