Subject: [core] Response codes for POST

From: Klaus Hartke <[email-masked]>
Date: Fri, 28 Jan 2011 23:14:12 +0100

It has been mentioned in the webex call and on this mailing list that
there should be a response code with payload for POST requests. I,
too, agree that this would be useful to have.

We need to be specific what the properties/semantics of that response code are.

Each response code needs to define the following properties:

- What methods does the response code apply to.
- Is payload required or optional or forbidden.
- What is the meaning of the payload (for example, the payload in a
successful response to a GET request is a representation of the target
resource; the payload in an error response is a human-readable
diagnostic message).
- What is the format of the payload (for example, the format in a
successful response to a GET is indicated by the Content-Type option;
the format of the payload in an error response is always Net-Unicode
text).
- Is the response cacheable (max-age).
- Is the response validatable when cached (etag).
- Does the response mark stored responses for the request URI as stale.
- Does the response mark stored responses for the Location URI become as stale.

To summarize coap-04, the success response codes are currently defined
as follows:

+-------------+-------------------------+---------+---------+------+-------+
| Request     | Response                | Payload | Max-Age | Etag | Stale |
+-------------+-------------------------+---------+---------+------+-------+
| GET         | 2.00 OK                 | x       | x       | x    | -     |
| GET + Etag  | 2.03 Valid              | -       | updates cache  | x     |
| GET + Etag  | 2.00 OK                 | x       | x       | x    | -     |
| POST        | 2.01 Created            | -       | -       | -    | x     |
| POST        | 2.01 Created + Location | -       | -       | -    | x     |
| POST        | 2.04 Changed            | -       | -       | -    | x     |
| PUT         | 2.04 Changed            | -       | -       | -    | x     |
| PUT         | 2.01 Created            | -       | -       | -    | x     |
| DELETE      | 2.02 Deleted            | -       | -       | -    | x     |
+-------------+-------------------------+---------+---------+------+-------+

You'll notice that many of the response codes have the same
properties/effects. The reason for this is that coap-04 aims to
indicate what happened semantically, rather than define one response
for each unique combination of effects. Illustrating  example from
HTML:

<i>text</i> has the effect of making the text be rendered in italics
(often used for emphasis)
<em>text</em> indicates emphasized text (often rendered in italics),
i.e. the semantic meaning

I think having the response code indicate what happened semantically
is a useful property to have. We should try to keep it.

Now on to the response codes for POST.

Currently, a 2.00 (OK) response is defined to be cacheable. This makes
it unsuitable for POST responses, because we invoke the POST method
for its side-effects, not its return value. In the webex call, we
agreed that it might make sense to create a new success response code
for GET requests (say, 2.05), so 2.00 (OK) can be used to indicate
general success.

So we have three changes:

- Rename 2.00 to, say, 2.05, to be used for GET responses;

- Add a new code indicating general success; and

- Add a new code for POST responses with payload.

(I believe the two new codes will not have the same properties, so I
listed them separately.)

Here are a couple of questions to get the discussion started.

Question 1.)

What's a good name for the code used for responses to GET requests?

The name "Your request was successful and here's the resource
representation you've asked for" is too long :-)

Question 2.)

What should be the properties of the general success code?

Proposal:
- Applies to any method
- Payload must be ignored by any recipient
- Not cacheable or validatable
- Does not mark stored responses as stale, except if defined by method
- Does not use the Location Option

This would define the general success code that is currently missing
from coap-04:

"However, there is no generic Response Code indicating success, so a
Response Code in the Success class that is unrecognized by an
end-point can only be used to determine that the request was
successful without any further details."

Question 3.)

What are some good example use-cases for POST responses with payload?

The only example given so far is that of merging two resources, which
in my opinion is not a good example to motivate POST responses with
payload. In that example, a POST takes two URI arguments, merges the
two resources into a new resource, and deletes the old resources. What
we'd ideally like to say in the response would be this:

- The operation was successful
- This information is not cacheable
- The old resource #1 was deleted; any stored response for that URI
should be marked as stale
- The old resource #2 was deleted; any stored response for that URI
should be marked as stale
- A new resource was created at Location #3; any stored response for
that URI should be marked as stale
- The target resource did not change
- No payload

We don't have a response code for this, so we need select a response
code that comes close. It seems to me a simple 2.01 Created + Location
of the new resource would be the best solution here, because the
client needs to be informed of the URI of the newly created resource,
and it doesn't hurt too much that stored responses for the two deleted
URIs aren't marked as stale.

I guess there have to be tons of good examples to motivate POST
responses with payload. Please list some that come to your mind.

Question 4.)

What should be the properties of POST responses with payload?

Proposal:
- Applies only to POST (not to PUT or DELETE)
- Payload may be a representation of the resource, or something else,
depending on the operation performed by the server
- Payload format is determined by Content-Type option
- Not cacheable or validatable
- Marks any stored responses for request URI as stale
- Does not use the Location Option

Question 5.)

This is probably the most interesting question. What are the semantics
of a POST response with payload? What happened when such a response is
sent? What can an intermediary infer when it sees one?

Did the target resource change?
Did another resource change?
Was a new resource created?
Was an existing resource deleted?
Did the server just compute something without changing anything?

Klaus

---

From: Guido Moritz <[email-masked]>
Date: Mon, 31 Jan 2011 10:15:42 +0100

Klaus,

thank you for your detailed analyses. There are details in your text about
the design of CoAP I was not completely aware while reading only the draft.

I will try to answer few of your questions.
> What should be the properties of the general success code?
+1
> - Payload must be ignored by any recipient
Why? If the general success code is so generic, it will depend on the
application if payload is required or not.

> responses with payload. Please list some that come to your mind.
I love POST to be interpreted as "server, please process my response and
give me the result." This may be a new resource or maybe even two. Or no
resource being created and I just get the response for my request. But since
the "please do what you have to do with this data and give me the answer" is
so generic, defining if and which payload is included is not that simple.
For our SOAP over CoAP binding we have both cases: One way request exchange
pattern without payload in the ACK and two way request response exchange
pattern with payload in the ACK.

> - Applies only to POST (not to PUT or DELETE)
Wouldn't the generic OK be sufficient, since POST is 'somewhat' generic too?
> depending on the operation performed by the server
+1
> - Payload format is determined by Content-Type option
+1
 
> Did the target resource change?
Depends on the response code. 2.04. indicated changed resource.
> Did another resource change?
Location + 2.04
> Was a new resource created?
Location + 2.01
> Was an existing resource deleted?
2.02
> Did the server just compute something without changing anything?
2.00 OK

Guido

> -----Ursprüngliche Nachricht-----
> Von: [email-masked] [mailto:[email-masked]] Im Auftrag von
> Klaus Hartke
> Gesendet: Freitag, 28. Januar 2011 23:14
> An: core
> Betreff: [core] Response codes for POST
> 
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core

---

From: Matthieu VIAL <[email-masked]>
Date: Mon, 31 Jan 2011 12:04:25 +0100

Hi Guido,

I don't understand in your proposition the exact semantic attached to the 
payload in the response.
Is the following proposition acceptable?

>> Was a new resource created?
The payload is the representation of the new resource. This should be used 
only if the new resource is not identical to the representation submited 
in the request (the server may add a timestamp or an automatically 
incremented ID for example). It is then an optimization to avoid a GET on 
the created resource.
Or some kind of extended code to provide a detailed status of the 
operation. For example the client may determine from this code that a 
subsequent GET is needed to get the exact representation of the new 
resource.

>> Did another resource change?
same as previous

>Depends on the response code. 2.04. indicated changed resource.
same as previous

>> Was an existing resource deleted?
The payload is a representation of the last state before deletion. How the 
server can decide if the client is interested in the last state?
I'am not in favor of having 2 methods to delete a resource to keep the 
interface simple and uniform. But an "invoke" POST could be used to make 
an atomic operation on several resources just like the merge example from 
Klaus.

>> Did the server just compute something without changing anything?
The payload is the result of an "invoke" POST

Matthieu

---

From: Guido Moritz <[email-masked]>
Date: Mon, 31 Jan 2011 12:34:02 +0100

Matthieu,

See my comments inline.

Guido

> Von: Matthieu VIAL [mailto:[email-masked]]
> Gesendet: Montag, 31. Januar 2011 12:04
> An: Guido Moritz
> Cc: 'core'; [email-masked]
> Betreff: Re: [core] Response codes for POST
> 
> Hi Guido,
> 
If POST results in exactly the same resource like the submitted one, isn't
this a PUT and not a POST?

> subsequent GET is needed to get the exact representation of the new
In general yes, to avoid an additional GET for a new resource. Maybe the
response resource (i.e. is the newly created one) is only a temporary one,
valid only for this single request. So the server does not have to create a
new one, but just sends it out and after transaction can forget about

> an atomic operation on several resources just like the merge example from
If you want to delete, use DELETE. But what if it depends on some
application logic if a resource is deleted. Something like "Delete if
TEMP>25, otherwise keep it." A deleted resource must not be integrated in
the payload. (or are their applications for logging and roll-back to keep
the last state at the client?)

> The payload is the result of an "invoke" POST
Yes.

---

From: Klaus Hartke <[email-masked]>
Date: Mon, 31 Jan 2011 16:57:22 +0100

>> What should be the properties of the general success code?

On second thought, what's the meaning of a generic success response
to, e.g., a GET?

> application if payload is required or not.

What's the meaning of payload in a generic success response? (Assuming
a generic success response is different from a success response to a
POST that created/updated/deleted/computed something.)

> resource being created and I just get the response for my request.

Agreed.

> pattern with payload in the ACK.

SOAP over CoAP isn't exactly a *good* example ;-) Need moar.

> Wouldn't the generic OK be sufficient, since POST is 'somewhat' generic too?

When we have finished designing the generic OK and the response code
for POST, and there seems to be no difference between the two, we can
assign the same number to them. But I'd like to keep the two issues
separated for now.

(Example: The current success responses to POST and PUT were designed
separately. But the result was that the "Created" response to a POST
and the "Created" response to a PUT were so similar, that I assigned
both the code 2.01)

>> - Payload format is determined by Content-Type option

An interesting question is also how to use the Block Option with a
POST where both request and response have payload.

>> Did the server just compute something without changing anything?

So you suggest to allow payload with 2.01 and 2.04, so a server can
include the result of a POST in the response? 2.01 and 2.04 are also
used for PUT.

What's the meaning of payload in a response to a PUT? If it's a
representation of the updated resource, shouldn't the response be
cachable?

Klaus

---

From: Guido Moritz <[email-masked]>
Date: Mon, 31 Jan 2011 17:14:17 +0100

Comments inline.

Guido

> Gesendet: Montag, 31. Januar 2011 16:57
> An: core
I would say it is the same for both. So maybe it is not required a new
response code for a GET, but just remove the dependency of 2.00 OK to a
specific method?

> SOAP over CoAP isn't exactly a *good* example ;-) Need moar.
Yea, it is not. But maybe a good example for an application profile on top
of CoAP ;)

> POST where both request and response have payload.
There is a small thread on the list, that maybe the current block design can
be used with deferred responses:
http://www.ietf.org/mail-archive/web/core/current/msg01508.html
Maybe in future versions of block the door should be kept open. 

> include the result of a POST in the response? 2.01 and 2.04 are also
Sounds reasonable.

> representation of the updated resource,
As I understand, PUT is "Replace existing with this one or create of not
exists". So there is no need to response with the resource. But POST may
result in a resource (or something else the server made of the request)
different from the one I sent 

> shouldn't the response be cachable?
Jep.

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 31 Jan 2011 17:24:40 +0100

> Maybe in future versions of block the door should be kept open. 

I'm working on a good solution for that.
(Not that I think it's particularly important, but it is sure nice to be more general here.  As long as it doesn't increase complexity.)

Gruesse, Carsten

---

From: Matthieu VIAL <[email-masked]>
Date: Mon, 31 Jan 2011 17:34:20 +0100

>this a PUT and not a POST?

The idea is:

REQ: POST /alrm
<alrm type="fire"/>
RES: 2.01 Created /alrm/1
<alrm id="1234" type="fire"/>

instead of

REQ: POST /alrm
<alrm type="fire"/>
RES: 2.01 Created /alrm/1

REQ: GET /alrm/1
RES: 2.00 OK
<alrm id="1234" type="fire"/>

or

REQ: POST /alrm
<alrm type="fire"/>
RES: 2.01 Created /alrm/2

if

REQ: GET /alrm/2
RES: 2.00 OK
<alrm type="fire"/>

But the client may not directly be interested in the final representation 
especially if it is quite large.

Matthieu

---

From: Guido Moritz <[email-masked]>
Date: Mon, 31 Jan 2011 18:15:13 +0100

OK, got the point.
Using a subsequent GET is possible, but I would argue an overhead. In your
'emergency scenario' you could (by means of numbers of messages) half the
network load.

REQ: POST /alrm
<alrm type="fire"/>
RES: 2.01 Created /alrm/1
<alrm id="1234" type="fire" derivedResult ="showOnScreen">Evacuation</alrm>

> especially if it is quite large.
Agreed. But this is responsibility of the application developer if payload
is included or not. So don't use a MUST or MUST NOT, but something which
allows it if required.
Btw, a GET may also result in a very huge result. You may have information
of the expected size during the discovery, but if the resource is changed by
a third party between discovery and invocation, you might not get what you
expected. 

Guido

> Gesendet: Montag, 31. Januar 2011 17:34
> An: Guido Moritz
> Cc: 'core'
> Betreff: RE AW: [core] Response codes for POST
>

---

From: Klaus Hartke <[email-masked]>
Date: Mon, 31 Jan 2011 19:11:42 +0100

> <alrm id="1234" type="fire"/>

I think we are getting too clever here.

An intermediary that sees an exchange like this

> <alrm id="1234" type="fire"/>

knows exactly what's going on and will do the right thing regarding,
e.g., cache invalidation and updating. A client receives the location
of the created resource and can decide what it wants to do next. The
two operations are decoupled and can evolve independently. These all
are good properties of a RESTful design.

Klaus

---

From: Guido Moritz <[email-masked]>
Date: Mon, 31 Jan 2011 19:57:06 +0100

> are good properties of a RESTful design.
RESTful yes, but not necessarily for resource constrained environments.

Guido