Re: Generic vs specific patch formats

On 11 Feb 2013 05:05, "Jan Algermissen" <[email protected]> wrote:
>
>
>
> Hi,
>
> trying to wrap my head around the implications of using generic patch
media types (e.g. json-patch[1]) vs. specific ones, e.g.
application/vnd.bigco.customer-patch.
>
> Generic JSON patch looks sort of fine, but I can make myself stop feeling
it's tunneling out of band knowledge.
>
> When the client constructs the patch document, it makes assumptions about
the (abstract) structure of the target resource that is essentially out of
band knowledge.
>
> You might argue, that the client will have learnt the structure from a
previous GET...
>
> GET /customers/42
> Accept: application/vnd.bigco.customer+json
>
> 200 Ok
> Content-Type: application/vnd.bigco.customer+json
> ETag: "..."
>
> ... and that understanding the *specific* media type (and having an ETag)
acts as a counter measure for the patch format being generic.
>
> Alas ... I am not fully convinced.
>
> Thoughts?
>

Hi Jan,

Assuming hypermedia is driving your application, then the client will have
the necessary context (via some preceding link relation) telling it what
and how it can traverse to the resource and patch its state.

That link was contained within some response from the application, so the
control is in band. The semantics are in band provided there is some
uniform way of determining them from the link relation's value. The common
way to achieve this is to use a URL for the rel value and expose a
description document there.

This works for any kind of interaction (other than hitting entry points)
and is why there is, usually, no need for an API to use any custom media
types at all.

Cheers,
M