Subject: [apps-discuss] media type for partial JSON updates?

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Dec 2011 16:51:52 +0100

Hi,

a few days ago, there was an epic thread over on rest-discuss 
(<http://tech.groups.yahoo.com/group/rest-discuss/message/18011>) on the 
use of HTTP PUT for partial updates of JSON-modeled data.

(Of course we all know over here that PUT isn't for partial updates :-)

However, apparently many people currently do this, as it's simply 
convenient to send a subset of the object and have the server just 
update those fields.

Now it's obvious that these kind of requests really should use PATCH, 
because that's what it's for after all. What's missing here is a media 
type describing this, though.

Should we document patch semantics for this use case, and define a 
matching media type?

It might be a light-weight alternative to what 
<https://tools.ietf.org/html/draft-pbryan-json-patch-04> describes. For 
example, taking the example from 
<https://tools.ietf.org/html/draft-pbryan-json-patch-04#appendix-A.5>:

    {
        "baz": "qux",
        "foo": "bar"
    }

    A JSON Patch document:

    [
          { "replace": "/baz", "value": "boo" }
    ]

    The resulting JSON document:

    {
        "baz": "boo",
        "foo": "bar"
    }

...the alternative notation would be...:

    {
        "baz": "boo"
    }

...sent with PATCH and an internet media type such as 
"application/partial-update-json".

Feedback appreciated,

Julian

PS: And yes, this would only allow replacing things; but this might be 
good enough for many use cases. Not defining something for this will 
cause people to stick with PUT, or to use PATCH with an incorrect media 
type, which we should avoid.

---

From: mike amundsen <[email-masked]>
Date: Thu, 29 Dec 2011 11:07:38 -0500

Julian:

I think there is already an XML format for PATCH, right? (can't seem
to find it right now) It might not bee too much work to spin up a
parallel media type definition using the JSON format.

That document might be proper place to describe a typical PATCH media
type as (improvising here) "a format designed to *modify* an existing
entity rather than replace all or part of an existing entity and/or
introduce the notion of "partial updates" through the description of
the PATCH method.

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

On Thu, Dec 29, 2011 at 10:51, Julian Reschke <[email-masked]> wrote:
> (<http://tech.groups.yahoo.com/group/rest-discuss/message/18011>) on the use
> of HTTP PUT for partial updates of JSON-modeled data.
>
> However, apparently many people currently do this, as it's simply convenient
> to send a subset of the object and have the server just update those fields.
>
> because that's what it's for after all. What's missing here is a media type
> describing this, though.
>
> Should we document patch semantics for this use case, and define a matching
> media type?
>
> PS: And yes, this would only allow replacing things; but this might be good
> enough for many use cases. Not defining something for this will cause people
> to stick with PUT, or to use PATCH with an incorrect media type, which we
> should avoid.
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Dec 2011 17:46:04 +0100

> parallel media type definition using the JSON format.

Oh, there is already a proposal for a JSON-based patch format as well.

> introduce the notion of "partial updates" through the description of

Why would you want to describe this as part of a spec for an XML format?

Best regards, Julian

---

From: mike amundsen <[email-masked]>
Date: Thu, 29 Dec 2011 11:58:40 -0500

> Oh, there is already a proposal for a JSON-based patch format as well.

understood.

> Why would you want to describe this as part of a spec for an XML format?

i do not, my message here was too vague.

1) i assumed you were proposing a new document that discussed PATCH
for partial updates.
2) i meant to say that the document you propose "might be the proper
place.... etc."
3) i assumed your text "define a matching media type ... It might be a
light-weight alternative to what
<https://tools.ietf.org/html/draft-pbryan-json-patch-04> describes..."
meant you were proposing a NEW media type to register w/ the IANA and
i suggested the XML PATCH (RFC5621, i think) as a possible template
for designing a JSON variant that would be this NEW media type.

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Dec 2011 18:08:43 +0100

On 2011-12-29 17:58, mike amundsen wrote:
> ...

Oh, sorry.

> for designing a JSON variant that would be this NEW media type.

Ack; understood.

I think it would be simpler to define it as something that can be 
trivially transformed to the format defined in 
https://tools.ietf.org/html/draft-pbryan-json-patch-04; in that case we 
wouldn't even need to describe the actual semantics...

Best regards, Julian

---

From: mike amundsen <[email-masked]>
Date: Thu, 29 Dec 2011 13:57:44 -0500

Julian:

are you suggesting a new RFC?

mca

On Thu, Dec 29, 2011 at 12:08, Julian Reschke <[email-masked]> wrote:
> I think it would be simpler to define it as something that can be trivially
> transformed to the format defined in

---

From: Julian Reschke <[email-masked]>
Date: Thu, 29 Dec 2011 22:11:01 +0100

> are you suggesting a new RFC?

I think so.

---

From: mike amundsen <[email-masked]>
Date: Thu, 29 Dec 2011 16:18:14 -0500

i think that's a good idea.

mca

---

From: "Paul C. Bryan" <[email-masked]>
Date: Thu, 29 Dec 2011 21:36:54 -0800

> wouldn't even need to describe the actual semantics...

Is this something that just reduces the verbosity of the operations, or
are you talking something probably non-JSON for higher compactness? If
the former, then I'm game to either choose shorter operation names or at
least allow for aliases.

If the latter, what have you got in mind? I'm curious how it might
compare such an approach to merely taking a JSON Patch document (with
possibly shorter op names) and encoding in a binary variant such as
BJSON or UBJSON...

Paul

---

From: Julian Reschke <[email-masked]>
Date: Fri, 30 Dec 2011 09:29:44 +0100

> the former, then I'm game to either choose shorter operation names or at

I personally don't think yet another format is needed.

But: people are doing this already with PUT (although they should not), 
and it might me good to offer them a way to fix what they do by 
switching PUT to PATCH and application/json to something that actually 
describes the semantics of what they are doing.

Best regards, Julian