Hacker News Reader

Comment by weixiyen | Hacker News Reader

Is my API RESTful when I use (only) JSON? NO.

There is no predefined way to deal with link discovery in JSON.

It is kind of silly. Just add a reasonable convention and stick to it. {'href':'<url>', 'rel':'<linktype'} or something like that. Saying to throw away your JSON representation because you can't do links is ridiculous.

Once you add extra stuff, it's not JSON any more. If you pick a convention, document it, and then serve it as some other type ( like application/foo+json ) then you're good. It's true that there's no reason to throw away the _serialization_ format that JSON provides you, but if you serve application/json, then you can't have extra 'conventions.'

Presumably what you serve is not random JSON, it is already application specific in some ways (unless it is proxying or encapsulating other services, which is reasonable). So say there will already be conventions about how to service collections (/carts/ that will be an array of objects that look a certain way or or single items /carts/<carid>/ that is an individual shopping cart may represented as a single json object with some known keys and values). So having links and relationships is just another such convention isn't it?

How is linking now special in the sense that it can't be considered bona-fide JSON, if it is parsed by a JSON parser without error just like a shopping cart it.

Yeah I am not sure how important it is to say that I am serving applicaiton/foo+json or just application/json? I have been doing just application/json lately, I may very well be wrong about it.

I'm a big REST fan, but I think using a different mediatype is only important if the format is (or can become) generic and used by other services. For example, if you're serving a GeoJSON document, which is a open format used by many services, it makes sense to use a specific mediatype. If, on the other hand, the format is totally custom to your service, I don't really see the point, since the client parsing it must be custom too.

The only advantage I can see to using custom mediatypes is if you want to do versioning (+v1, +v2, etc).

Right, the point is to move this out-of-band information back in-band, so that

> How is linking now special in the sense that it can't be considered bona-fide JSON, if it is parsed by a JSON parser without error just like a shopping cart it.

Here's the definition of application/json: http://www.ietf.org/rfc/rfc4627.txt If my client accepts application/json, this is the only information that I can rely on for processing. Show me where links are defined in that spec.

They're not! Basically, we're having an implicit vs explicit argument: you're arguing that 'everyone should just know it's a convention I'm using, who cares?' and I'm saying 'By being explicit that you're using a convention, communication improves and everyone is more happy.'

Which is exactly what's happening: http://stateless.co/hal_specification.html

The Link header is a really good solution to this.

Reply on news.ycombinator.com