Is PATCH really needed?

[Enrique Amodeo]

Hi everybody, I've been studying the PATCH verb and I cannot make the
difference between issuing a PATCH with a diff document to an URI, and
doing a POST with a diff document to the same URI. Both methods are
unsafe and not idempotent, both methods append info to an existing
resource.
POST can be done against an existing URI to add content to it. If we
send a diff document I understand that it will add the diff to the
resource, doing effectively a partial update.
The only difference I see is that POST is more general than PATCH (you
can use it to other purposes).
Am I missing something? Why do we need a new HTTP method? Why is
better to use PATCH instead of POST?
Cheers,
Enrique Amodeo

[Mike Kelly]

In practice, there are no clear benefits of using PATCH over POST.

Using PATCH will make your interactions theoretically more
'self-descriptive' than using POST, since PATCH has more specific
semantics than POST does. However this additional visibility is not
particularly useful in practice, which is another way of saying "using
PATCH instead of POST doesn't allow you to implement any additional
intermediary mechanisms".

Using PATCH for partial updates instead of POST might make those parts
of your API faster to grok for developers, but there isn't a
significant functional reason to prefer it. If you are concerned about
the potential for any clients to struggle with issuing PATCH, then
just sticking to POST is the way to go.

Cheers,
M

--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[sune jakobsson]

Well, PATCH is a subset of POST, for those with "too much" data, and concern about the transport.

Sune

[Andrei Neculau]

One small addition is that beyond the benefit of having a clear expectation of what will happen (which you don't with POST), is that supporting PATCH, one should also advertise the accepted patch content-types with the Accept-Patch header.

Roy Fielding mentions somewhere that the meaning of using a HTTP method should not be bound to location, media-type, etc, but that the method should mean the same everywhere. I would assume that most operations are update operations (PATCH) and not do-anything-that-you-want-with-this-data operations (POST).

IMHO custom (even non Proposed/Draft/Internet Standard) HTTP methods could be rather helpful because the client (may it be the API client, or the HTTP client) can have different flows based on that, just like webmachine does http://wiki.basho.com/Webmachine-Diagram.html .

[Enrique Amodeo]

So far the only clear advantage of PATCH over POST is that is more
explicit. I'm not really sure if this is enough for all the
interoperability problems that introducing a new HTTP method would
add.
About Accept-Patch header, why not just simply use classic content
type negotiation?
Interesting point about web machine, I need to look deeper into this.

My fear is that we end with a lot of methods, one for each conceivable
operation that you can do on a web resource. Why not a bulk update
method for example?
Cheers,
Enrique Amodeo

[Andrei Neculau]

On Wednesday, May 30, 2012 8:59:34 AM UTC+2, Enrique Amodeo wrote:

My fear is that we end with a lot of methods, one for each conceivable
operation that you can do on a web resource. 

What do you see wrong with this, IFF all the custom methods are to be treated as POST by intermediaries (aka not safe, not idempotent, don't cache, etc) ? 

[Mike Kelly]

If they are treated as POST by intermediaries that kind of begs the
question: what is the point of them at all?

imo, HTTP should be focused on establishing semantics that make useful
contributions to the intermediary-processability of interactions.
Adding more specific methods that are practically indistinguishable to
an intermediary adds nothing in this respect and just bloats the
protocol with redundant additional semantics.

Cheers,
M

[Enrique Amodeo]

Mike, explained my point better than I :)
I fear bloating the HTTP protocol, and making it too complex. One
advantage of HTTP and REST style is that you have relatively few
verbs, with stablished semantics, this make easy to understand and
use.
On the other side, you can reasonably argument that POST semantic is
overloaded too much, and it is a kind of kitchen sink.
Cheers,
Enrique Amodeo

[Andrei Neculau]

On Wednesday, May 30, 2012 12:37:23 PM UTC+2, Enrique Amodeo wrote:

On the other side, you can reasonably argument that POST semantic is
overloaded too much, and it is a kind of kitchen sink.

+1

 

> If they are treated as POST by intermediaries that kind of begs the
> question: what is the point of them at all?

Are intermediaries treating GET and HEAD in any different way? I, at least, am not aware of that.

The fact that intermediaries can attain knowledge by looking at the HTTP method (and thus eg. retry a GET/PUT on network failure) is an added bonus, rather than a requirement for defining a HTTP method. Otherwise, HTTP methods would be defined against a matrix of safe & idempotent, in order to cover possible combinations and we would surely not have anything like "The set of common methods [...] can be expanded [...]" http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

Cheers!

[Mike Kelly]

On Wed, May 30, 2012 at 1:01 PM, Andrei Neculau
<andrei....@gmail.com> wrote:
> On Wednesday, May 30, 2012 12:37:23 PM UTC+2, Enrique Amodeo wrote:
>> > If they are treated as POST by intermediaries that kind of begs the
>> > question: what is the point of them at all?
>
>
> Are intermediaries treating GET and HEAD in any different way? I, at least,
> am not aware of that.

Yes, an intermediary can be used to add HEAD support to a legacy
application that only supports GET (by stripping out the body). Here
is a real world example of this:

https://github.com/rack/rack/blob/master/lib/rack/head.rb

> The fact that intermediaries can attain knowledge by looking at the HTTP
> method (and thus eg. retry a GET/PUT on network failure) is an added bonus,
> rather than a requirement for defining a HTTP method.

a bonus added to what? what is the core value of HTTP if it is not this?

> Otherwise, HTTP
> methods would be defined against a matrix of safe & idempotent, in order to
> cover possible combinations and we would surely not have anything like "The
> set of common methods [...] can be expanded
> [...]" http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

Yes, HTTP would be better off were that the case. (imo)

Cheers,
M

[Dale McCrory]

In regard to the value of explicit-ness in API construction. The fact
that PATCH is explicit for partials is notable in that behavior that
is not explicit is the common cause of poorly written clients or ugly
server side code. I've worked with APIs that put everything into a
POST - partials, bulk, creates, and updates. It's not pretty,
developer experience is really weak (both getting the proper
implementation and the performance characteristics of client-side
code).

One of the values of REST is a small set of operations that can be
tweaked, tuned, and optimized. Using POST as a catch-all doesn't help
with tweaking, tuning and optimizing operations because the client use
cases are so broad (you may as well go with SOAP :) ). I think you are
still advocating for the use of PUT, but I would say that if you say
PATCH is irrelevant, PUT can easily fall into the same basket.

Dale

[Mike Kelly]

On Wed, May 30, 2012 at 2:12 PM, Dale McCrory <dale.m...@gmail.com> wrote:
> In regard to the value of explicit-ness in API construction. The fact
> that PATCH is explicit for partials is notable in that behavior that
> is not explicit is the common cause of poorly written clients or ugly
> server side code. I've worked with APIs that put everything into a
> POST - partials, bulk, creates, and updates. It's not pretty,
> developer experience is really weak (both getting the proper
> implementation and the performance characteristics of client-side
> code).

I dont' think it should be HTTP's job to prevent people coming up with
poor designs.. where would you stop on that crusade? PATCH will not
solve that problem on its own.

> One of the values of REST is a small set of operations that can be
> tweaked, tuned, and optimized.

I agree, which is why diluting the protocol with virtually redundant
methods like PATCH is a problem.

> Using POST as a catch-all doesn't help
> with tweaking, tuning and optimizing operations because the client use
> cases are so broad (you may as well go with SOAP :) ).

Tweaking, tuning, and optimizing operations at the scale of the web is
about intermediary processing, if the operations themselves are not
suitable candidates for that then they should not be part of HTTP.

> I think you are
> still advocating for the use of PUT, but I would say that if you say
> PATCH is irrelevant, PUT can easily fall into the same basket.

If you want to follow the letter of the law don't use PUT for partial
updates (if you want to make the most of the protocol in practice, and
your updates are idempotent, then do use PUT).

PUT is fully idempotent and recognized as such across the web - PATCH
isn't. An idempotent request can be retried a number of times and
produce the same outcome, and this means that code issuing idempotent
requests (such as PUT) can act as an intermediary and re-issue failed
automatically. So PUT enables an intermediary mechanism that is
clearly useful, particularly on choppy networks such as 3g. I'm not
aware of any similar use for PATCH

Cheers,
M

[Enrique Amodeo]

It seems I would be forced to support both methods, and the infamous
X-HTTP-Override-Method, to support partial updates. Having two ways of
doing the same thing can be confusing.
I think the best thing to do is to try to avoid generic partial
updates, an model composite resources!
Cheers,
Enrique Amodeo

[Dale McCrory]

It may not be HTTP's job to prevent people from coming up with poor
client designs, but it is your job as an API designer to build an API
with a good developer experience that allows good client
implementations as easily as possible using the tools that HTTP
provides. API Craft is not just about what is HTTP, but how do you
design the best API using HTTP constraints.

Patch is not virtually redundant, because at some point you have to
explain to end developers whether a field is null or not on an update.
On a POST, it would be expected that fields not included to be NULL.
Otherwise, you have to then do the opposite -- explain how to get a
full update on an object. On a PATCH, it would be expected that fields
not included to retain their values.

Dale

[Mike Kelly]

On Wed, May 30, 2012 at 3:27 PM, Dale McCrory <dale.m...@gmail.com> wrote:
> It may not be HTTP's job to prevent people from coming up with poor
> client designs, but it is your job as an API designer to build an API
> with a good developer experience that allows good client
> implementations as easily as possible using the tools that HTTP
> provides. API Craft is not just about what is HTTP, but how do you
> design the best API using HTTP constraints.
>
> Patch is not virtually redundant, because at some point you have to
> explain to end developers whether a field is null or not on an update.
> On a POST, it would be expected that fields not included to be NULL.

Why would that be expected? There's nothing about POST which implies
that, afaik.

> Otherwise, you have to then do the opposite -- explain how to get a
> full update on an object.

Use PUT and explicitly set the values to null, or document your API to
make it explicit that PUT means full replacement (which is should
anyway according to HTTP).

> On a PATCH, it would be expected that fields
> not included to retain their values.

Yes, it is slightly easier for developers to grok. But adding some
documentation to your API like 'fields that are not included in a
partial update via POST retain their values', is not that big of a
deal. Either way, you still need to establish a diff media type.

Cheers,
M

[Enrique Amodeo]

I do not agree with the null fields thing. The semantic of conserving
the not specified fields is not in the verb, but in the mime type. I
can use POST with a mime type that explicitly represents "diff"
documents and this will solve the issue. I found that in REST APIs the
essence of the semantics is on the mime types, that's why a fixed set
of verbs are enough. REST is not RPC.

As I said in an early mail, I think is better to define the API in a
way that you can have "composite" resources. For example, a customer
resource at URI /customers/{id}, that only contains the most essential
data of customers and links to "detail" resources. These details have
their own URI, for example /customers/{id}/bank_info and
/customers/{id}/bill_addresses. This way you don't need partial
updates in most use cases, simply do a full update with PUT to the
"detail" resources. But this approach requires an upfront knowledget
of the use cases (this is fine if you are exposing the application
layer instead the data layer)

I find this approach less confusing than partial updates (this POST
vs. PATCH issues).

But I agree that in the case you want the client to do a generic
partial update, where it can update any combination of fields and
"details" objects, this design will not be enough. This is often the
case when you expose the data layer instead the application layer.

Cheers,
Enrique Amodeo

[Dale McCrory]

I guess the question is: Is a partial view of a resource a different
resource or is it the same resource with partial fields? I don't think
a partial view of a resource is a different resource. That doesn't
make sense because a client may have different parts of data and you
would need to accurately predict all of them to have a successful
design.

Additionally, the decision to make your partial resources displayed as
resources:
/people/124/name
Is as much of a decision about how your data is managed. If your
organization uses stored procedures, that may be an arduous task to
build the data layer out.

Additionally, if a client wants to update a person with 3 fields. You
are asking the client to:
1. Make a POST/PUT with all the data elements, or
2. Make a 3 POST/PUST calls

Both of which are unnatural for that client flow (and would make a
developer scream).

Dale

[Enrique Amodeo]

Exposing every single field as an URI is overkill. But you can group
frecuently accessed/updated fields in the same object (with an URI).
It's the same thing with old relational data bases. You usually don't
end up with a table with a lot of columns, but a master/detail design.

Anyway I think the best design depends on the use case. If you are
exposing your data layer, partial updates make sense. If you are
exposing application layer, you should structure the information in an
use case friendly way, hence not every combination of data is used.

But I think, I'm going offtopic here, sorry!
Cheers,
Enrique Amodeo