Also, there’s a new method called PATCH for HTTP. I still prefer links though.

PUTting the entire entity representation as in approach 1 just to change a single attribute seems overkill to me for several reasons.

1. Why should I send an entire object if I want to change only a single attribute?
2. Why should the server derive the callers intention by comparing two representations (one from the database and one that was sent)?
3. Why should the server read the object that is to be changed from the database before changing it?

What if the object was changed in the meantime in a way that makes it ambiguous for the server to determine the intent of the caller?

This all seems like a lot of code for a simple operation.

Bill, I like the atom links with rel=’terminate’ and an opaque URI. How does the caller know which HTTP verb to use? Is it always POST for atom links?

Frank

This is not so because the message can only be considered in isolation – it does not depend on any previous interaction – or if it does it is not self descriptive.

Besides all this – why not use a RESTful solution in the first place? Or just use the straight-forward DELETE /customers/22 ?

(Is this your blog? I’ll reply there too.)

I would agree with the assessment that if the “terminate” link supported multiple actions then it would be an antipattern and not REST. But in my example, the “terminate” link does not represent multiple actions. It represents a state transition to terminated. There’s absolutely no rule against one state change of one resource affecting another. Also, in my example, there is no unterminate on the “terminate” link. The “terminate” resource only accepts empty representations which mean to terminate (a form param of doit=true is just pedantic). Instead there would be a “reinstate” link published by the consumer resource. What I like about this approach is that the consumer resource is guiding the client on what it can do next by publishing links within its representation. This is the whole point of HATEOAS and alot more self descriptive, especially if there are more complex rules for when and if a the consumer can be terminated or reinstated that can’t be described by the media type easily.

I also don’t get your timing point. Is your point that between T2 and T5 the state of the consumer may change and terminate becomes illegal? The server is always allowed to return a failure if the POST cannot be processed (i.e. precondition failed) if the timing is off and the terminate transition becomes illegal.

Finally The blog states that “There is nothing in the request that allows the server to understand the actual intention of the client at the time the server handles the POST request.” The server is receiving an empty representation. The server published (through the link) that it expects “empty” representations to do the terminate transition. Of course the server is going to understand the intent of the request, because that’s all it accepts. Again, if you’re into pedantic exercises, define a null media type or doing a form param doit=true. I’m not.

ask yourself: when the server receives POST [empty] /customers/22/terminate, how does it verify that the client’s intention matches the current intended processing done by /customers/22/terminate?

See http://www.nordsc.com/blog/?p=414

You’ll have to explain your self-description argument here. The meaning of a POST in my terminate resource example is the same no matter when the request is executed. The meaning is to change the state to terminated. So, I don’t understand what you mean when you say that “the meaning of the request depends on server side state”. Also, considering Roy in his thesis says “REST constrains messages between components to be self-descriptive in order to support intermediate processing of interactions” I don’t see your point at all (he goes on to describe various *request* metadata). POST responses are not cached anyways.

What I am trying to say is that you don’t need a ‘edit’ link when PUT does just the same. Why would you want the “edit” link to point at the same resource, when PUT is much simpler, cleaner and (especially if the customer+xml is properly designed) even self-describing?

I can imagine that idea like rel=”edit” comes from Atom, but I am afraid is often taken out of context and “re-used” blindly. Where links like rel=”edit” come useful is if the content type is xhtml and you require a web form to be able to (eventually) perform a PUT. This is due to the fact that you can’t just let a user to submit a PUT out of thin air and need a client to do so anyway. That’s why “edit” links often point at a form that simply allow in a user-friendly way to fill a form and eventually perform the very same PUT.

Now, coming back to your example… The link rel=”terminate” would certainly work. But that’s not the point that I am trying to make.

The first point that I am trying to make out of it is that if terminate property is all (or almost all) there is to it then you don’t need a link with a special meaning. Just change the property(ies) value and do a PUT. The url and standard HTTP methods for that are known! The terminate property is already in the customer resource and is properly modeled in the meda type. Having a link for that is not necessarily wrong but can be superfluous.

Another point that I am trying to make, is that *if* termination is not just a single property and actually needs to be a *separate* resource then having a link pointing at the termination resource might make sense (although I still wouldn’t like it and use as a last resort when no better option/redesign is possible).

I guess there may be different reasons many sites don’t use Approach #1:
* They just use Atom and don’t care about being RESTful which may happen alot in publishing/blogs. This is not to say Atom is not RESTful! You can be as RESTful or unRESTful with Atom as you wish.
* Their RESTful interface is built mainly for humans and not robots (hence the usefulness of “edit” links that would point at the edit form which in turn will facilitate the PUT’ting).
* Overly complexity of resource model (see reasons I described above).
* Lack of understanding of REST principles. I also see many sites doing all kinds of unnecessary ‘creativity’ such as putting action in a URL (e.g. action=delete) or other RPC-ish stuff.
* Whatever other, not mentioned here, reason (which I might have easily missed).