Re: REST: Typed resources

Am 18.12.2015 15:59 schrieb Tomasz Pluskiewicz <tomasz@t-code.pl>:
>
> 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.

Very important is the [ditto] immediately after your quote. It resolves to  [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC’s functional coupling].

What must be avoided is coupling of clients to out-of-band information what a response means and what to do with it. The obvious example would be a vendor-specific api where you need a separate document which describes response types, attributes and URLs. I know - that's how today's api industry does things.

Strictly binding to media-types and standard rels allows applications to work like a newsreader: subscribe feeds from servers without writing a new client for each feed.

>
> 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.

There has been extensive discussion on mnot's blog about the proliferation of media types and the consensus was that proliferation of media types is not a good thing. Standardized profile URLs are the preferred concept. The presence of a known profile URL tells the client that it can expect specific attributes and semantics according to that profile. Real world examples are podcasts, hcards.

RDF is competing with that concept: every thing, every attribute and every non-primitive value gets a URL of its own.

For practical purposes, shared profiles might prove to be more useful for newsreader-like generic clients since they close the world sufficiently to make sense for a client. A common "retail" profile or a "movie" or "heating" profile is more straightforward to implement than an RDF response which can express the whole world, but promises nothing in particular.

The lithmus test for a decoupled client is: can a client use the capabilities of my service without knowing it in advance?
*That* is basically how the web works.

Vendor-specific vocabs are not going to cut it, it doesn't help that everything has a URL. If common vocabs (schema.org) will work to build generic clients is yet to be proved.

Best regards,
Dietrich