The convention that Django REST Framework (which is an add-on for Django, not part of the core) uses is to add a 'url' attribute to each resource to represent the cannonical id.<p>Even better, when you hit the API with a browser, you can click around and explore the links easily:<p><a href="http://restframework.herokuapp.com/users/" rel="nofollow">http://restframework.herokuapp.com/users/</a><p>The docs talk about it a bit here:<p><a href="http://django-rest-framework.org/tutorial/5-relationships-and-hyperlinked-apis.html" rel="nofollow">http://django-rest-framework.org/tutorial/5-relationships-an...</a>
<i>...I came up with a simple media type that adds linking on top of JSON</i><p>Adding hypermedia reflection to JSON does amazing things to APIs. We've been doing this via oData for awhile, and it makes things so much easier on the client. Anyone building a hypermedia/REST API with JSON (or XML) would make good of using standard formats that incorporate this functionality and attitude.
This doesn't need to be a Rails feature. Rails is for building web apps. There is a whole bunch of extra stuff Rails does that a web api doesn't need to care about. So, it really doesn't need to be a mvc web app framework feature.<p>Also, why tie this idea to Rails at all? Why not just make your own plugin or Sinatra app or frameowrk or whatever?
I blogged about this same idea in response to a different article 3 months ago. Seems like the hypermedia discussion keeps coming up. Here's my response article: <a href="http://rtigger.com/blog/2012/08/27/discovering-the-value-in-discoverable-apis/" rel="nofollow">http://rtigger.com/blog/2012/08/27/discovering-the-value-in-...</a><p>TL;DR - there's no value in discoverable (hypermedia) APIs short of some generic API browser that end users don't really want.
Isn't this what the Link header is for? Why put them in the JSON?<p>The only reason I'm aware of is for compatibility with JSONP. Github's API normally uses Link headers, but adds a "meta" object for JSONP requests: <a href="http://developer.github.com/v3/#json-p-callbacks" rel="nofollow">http://developer.github.com/v3/#json-p-callbacks</a>