REST, Hypermedia, and JSON
Enjoying Sam Ruby’s latest post titled Connecting, I was reminded that designing a RESTful system means much more than just adhering to a uniform interface (often the first attribute of a ROA that is promoted).
When designing a Resource Oriented Architecture, you mustn’t forget about hypermedia and how your resources link to one another, and how those links are expressed through your representations.
Which brings me to JSON. A nifty little format, indeed. And one that, if you are building a modern web service, you should be investigating and implementing. However, if you are indeed building a hypermedia system with JSON, how do you express your links?
I know how to do this in XHTML and RDF, but not sure how to express or render a URI and have it mean “link”.
I’ve love to be able to do something like this:
{
"name": "Cool Beans",
"account": "http://example.org/accounts/23242342"
}
However, any JSON client will have a tough time determining what the meaning of the account value is. Sure, it’s a string. But how should it be treated? And how do I express that to my JSON clients? I’m not about to give them a regular expression and say “if it matches, it’s a URI, and follow it!”
Thoughts? How to express hypermedia in JSON?
March 23rd, 2008 at 11:23 pm
I worked on a “tourist system” in 1989-1990 direction using HyperCard. We ended up putting all the hyperlinks in a database.
March 24th, 2008 at 12:18 am
Why not borrow the approach used in the SPARQL JSON results format? E.g.
"account": { "type": "uri" , "value": "http://example.org/accounts/23242342" } ,
March 24th, 2008 at 8:15 am
I looked at the SPARQL JSON mapping, but it’s too verbose for my use case. I don’t want to have to set the type and value for every attribute.
For now, I’m simply using a fully qualified URI as the value for an attribute. It’s up to the client to read the docs or specs to learn which attributes in the JSON are URIs.
I’m happy I’m including URIs (links) in my JSON. Feels much more webby.
March 24th, 2008 at 11:30 am
doing regex on a bunch of strings to guess if theyre URIs really smells.
i use {uri: ‘http://someuri”} instead of a string.
but i think URIs are realy important as a first class element of the syntax, and N3 is already invented, so the clock is ticking on JSON
March 24th, 2008 at 11:35 am
Agreed, you don’t want to guess if the string is a URI. The simple hash is a good option there.
And while formats like N3 have identified URI as a first class type, JSON has so many tools and is integrated directly into the language of the Web (Javascript) that it’s going to take a lot to replace JSON with N3.
I definitely intend to return HTML, JSON, RDF/XML, and Turtle.
April 3rd, 2008 at 7:28 am
More than just tagging your URIs in your JSON format, you have to define somewhere (in your format spec) what the client can do with them or your representations fail to be self-describing. There’s no generic way for including hypermedia in JSON to my knowledge, so you’d need to define your own “application/myformat+json” media-type.
In HTML it is perfectly defined what a client can do with the HREF value in an anchor tag or with the URIref in the ACTION attribute of a FORM. It’s not so in plain RDF, unless you define that resources having certain types can be GET, PUT or POSTed to. There’s an attempt at this called RDF Forms http://www.markbaker.ca/2003/05/RDF-Forms/ .
April 17th, 2008 at 6:52 am
[…] On software architecture, Connecting, REST, Hypermedia, and JSON […]