REST: Typed resources

Hi Hydranians,

I've been reading a lot about broadly understood hypermedia APIs and I've come across the classic Roy Fielding's post REST APIs must be hypertext-driven [1]. In that post Mr Fielding brings up a number of points that I agree with and generally think should be obvious for a person who understands REST. Among those is one that I'm don't really tie in with especially in the context of RDF and Hydra:

A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names.

I've already expressed my dislike for the emphasis put on Media Types on this list. I consider RDF the missing link in providing metadata and semantics. It seems to me that media types are a dead end, because unless a server wants to provide resources in very different representations such as hypermedia, vcard, image or audio it's fine. But with each individual server serving a different hypermedia type, not to mention any possible vnd.*? How would that work? Let the client receive a representation with media type vnd.my-cool-type+json;type=Person. Without knowledge of the parameter's meaning and vendor extension it has to fall back to plain JSON. If it has a weird document structure like HAL, SIREN or Collection+JSON does it's pretty much useless.

I see the motivation here. First, the client should not have to parse the representation if the media type it does not understand. Also there is the assumption that such "typed resource" would expose server's implementation details, ie. class name. However with RDF type type doesn't really work this way. It doesn't have to match any server side storage or implementation class but rather serve as metadata with Hydra being it's a hypermedia extension.

I'm not sure what to make of it. Hove any of you had similar reflections? If so, and you agree with Roy Fielding, maybe it makes sense to extend the default media type with resource type, so that clients don't have to rely on the representation too much?

Thanks,
Tom

[1]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Received on Friday, 18 December 2015 14:59:14 UTC