Subject: [core] coap #77 (new): Response code semantics

From: "core issue tracker" <[email-masked]>
Date: Sun, 21 Nov 2010 21:16:05 -0000

#77: Response code semantics

 The current draft implicitly imports the meaning of response codes from
 HTTP. This ticket is to make the semantics of the response codes explicit
 in the draft.

-- 
----------------------------+-----------------------------------------------
 Reporter:  hartke@…        |       Owner:  zach@…            
     Type:  enhancement     |      Status:  new               
 Priority:  major           |   Milestone:                    
Component:  coap            |     Version:                    
 Severity:  -               |    Keywords:                    
----------------------------+-----------------------------------------------

Ticket URL: <http://trac.tools.ietf.org/wg/core/trac/ticket/77>
core <http://tools.ietf.org/core/>

---

From: Klaus Hartke <[email-masked]>
Date: Fri, 26 Nov 2010 00:35:04 +0100

I've extracted some text from draft-ietf-httpbis-p2-semantics-12 and
adapted it to CoAP.

# Response Codes

Each response code is described below, including any options required in the
response.

## Successful 2xx

This class of status code indicates that the client's request was successfully
received, understood, and accepted.

### 200 OK

The semantics of the response are dependent on the method used in the request.

- GET: The request has succeeded.

  The payload returned with the response is a representation of the target
  resource. The payload format is specified by the media type given in the
  Content-Type Option.

  The response is cacheable: Caches can use the Max-Age Option to determine
  freshness (freshness model) and (if present) the Etag Option for validation
  (validation model).

### 201 Created

The semantics of the response are dependent on the method used in the request.

- PUT: The representation enclosed in the request was successfully stored at
  the request URI, which resulted in a new resource being created.

  The payload returned with the response is empty. The Content-Type Option, the
  Max-Age Option and (if present) the Etag Option refer to the created resource
  and its current representation after the requested action.

  The response is not cacheable. However, caches can construct and store a 200
  (OK) response from the representation enclosed in the request, and the
  Content-Type, Max-Age and (if present) Etag Option in the response.

- POST: The request has resulted in a new resource being created. The newly
  created resource can be referenced by the Location Option. The origin server
  MUST create the resource before returning the 201 response.

  The payload returned with the response is empty.

  The response is not cacheable.

### 204 No Content

The semantics of the response are dependent on the method used in the request.

- PUT: The representation enclosed in the request was successfully stored at
  the request URI.

  The payload returned with the response is empty. The Content-Type Option, the
  Max-Age Option and (if present) the Etag Option refer to the target resource
  and its current representation after the requested action.

  The response is not cacheable. However, caches can construct and store a 200
  (OK) response from the representation enclosed in the request, and the
  Content-Type, Max-Age and (if present) Etag Option in the response.

- POST: The representation enclosed in the request was accepted and processed
  as data by the target resource.

  The payload returned with the response is empty.

  The response is not cacheable.

- DELETE: The target resource was successfully deleted.

  The payload returned with the response is empty.

  The response is not cacheable.

## Redirection 3xx

This class of response code indicates that further action needs to be taken by
the client in order to fulfill the request.

### 304 Not Modified

The semantics of the response are dependent on the method used in the request.

- GET: The response to the request has not been modified since the response
  identified by the Etag Option in the request.

  The payload returned with the response is empty.

  When a cache receives a 304 response, it needs to created an updated response
  by combining the stored response with the 304 response, so that the updated
  response can be used to satisfy the request, and potentially update the
  cached response. This is detailed in section TBD.

## Client Error 4xx

This class of response code is intended for cases in which the client seems
to have erred. These response codes are applicable to any request method.

The server SHOULD include an human-readable message as payload containing an
explanation of the error situation. The format of the payload is plain/text
(UTF-8).

Responses of this class are cacheable: Caches can use the Max-Age Option to
determine freshness (freshness model). They cannot be validated though.

### 400 Bad Request

The request could not be understood by the server due to malformed syntax.
The client SHOULD NOT repeat the request without modification.

### 4xx

The request could not be understood by the server due to one or more unknown
critical option. The client SHOULD NOT repeat the request without modification.

### 403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization
will not help and the request SHOULD NOT be repeated.

### 404 Not Found

The server has not found anything matching the request URI. No indication is
given of whether the condition is temporary or permanent.

### 405 Method Not Allowed

The method specified in the request is not allowed for the target resource.

## Server Error 5xx

This class of response code indicates cases in which the server is aware that
it has erred or is incapable of performing the request. These response codes
are applicable to any request method.

The server SHOULD include an human-readable message as payload containing an
explanation of the error situation. The format of the payload is plain/text
(UTF-8).

Responses of this class are cacheable: Caches can use the Max-Age Option to
determine freshness (freshness model). They cannot be validated.

### 500 Internal Server Error

The server encountered an unexpected condition which prevented it from
fulfilling the request.

### 501 Not Implemented

The server does not support the functionality required to fulfill the request.
This is the appropriate response when the server does not recognize the request
method and is not capable of supporting it for any resource.

### 502 Bad Gateway

The end-point, while acting as a proxy or reverse proxy, received an invalid
response from the upstream server it accessed in attempting to fulfill the
request.

### 503 Service Unavailable

The server is currently unable to handle the request due to a temporary
overloading or maintenance of the server. The implication is that this is a
temporary condition which will be alleviated after some delay. The length of
the delay is indicated in the Max-Age Option.

### 504 Gateway Timeout

The end-point, while acting as a proxy or reverse proxy, did not receive a
timely response from the upstream server specified by the request URI (e.g.,
CoAP, HTTP) or some other auxiliary server (e.g., DNS) it needed to access in
attempting to complete the request.

---

From: "Angelo P. Castellani" <[email-masked]>
Date: Fri, 26 Nov 2010 09:27:27 +0100

Cannot we simply link to that document and preserve the meanings in CoAP?

If there are differences or exceptions, we can pinpoint them in the
CoAP document...

Mapping and interoperability will be obtained more easily.

Regards,
Angelo

On Fri, Nov 26, 2010 at 00:35, Klaus Hartke <[email-masked]> wrote:
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core
>

---

From: Klaus Hartke <[email-masked]>
Date: Fri, 26 Nov 2010 12:15:23 +0100

> Mapping and interoperability will be obtained more easily.

CoAP already defines its own versions of the method codes, which are
compatible but subtly different to the methods defined in HTTP. The
same applies to the response codes: They are compatible but slightly
different.

For example, we don't have conditional requests in CoAP. This changes
the semantics of 304 (Not modified) which now is used to indicate that
a cached representation is fresh when a client submits an Etag.

If we simply link to HTTP and specify the differences, I believe the
resulting text will not be much shorter than what I posted. So I'm
more in favour of defining the response code semantics directly in
CoAP.

Klaus

---

From: Peter Bigot <[email-masked]>
Date: Fri, 26 Nov 2010 06:07:05 -0600

A second proposal (in addition to not using decimal grouping): don't try to
match HTTP response code values with CoAP ones if the semantics are
different.  Especially if they're subtly different.  We'll confuse folks
into thinking there's a rote mapping from one to the other.

Peter

---

From: "Angelo P. Castellani" <[email-masked]>
Date: Fri, 26 Nov 2010 16:24:43 +0100

To allow HTTP mapping the code equivalence should be preferred (until
the differences are subtle, and no particular issue can be imagined).

However to be better informed about the differences and the possible
issues, is important at least that these differences are clearly
described in the coap document.

Angelo

---

From: Klaus Hartke <[email-masked]>
Date: Fri, 26 Nov 2010 16:38:06 +0100

> described in the coap document.

So in Section 7 (HTTP Mapping) we'd need to point out that

* a request from a CoAP client to an HTTP server that includes an Etag
is mapped to a conditional request;

* a request from an HTTP client to a CoAP server that is conditional
is only supported if the request includes a If-None-Match header with
exactly one Etag. If-Match, If-Modified-Since and If-Unmodified-Since
are not supported, as is If-None-Match with more than one Etag;

* the semantics of a CoAP 304 (Not modified) response include only a
subset of the semantics of an HTTP 304 (Not Modified) response.

Is that about right?

Klaus

---

From: "Angelo P. Castellani" <[email-masked]>
Date: Fri, 26 Nov 2010 16:42:49 +0100

> subset of the semantics of an HTTP 304 (Not Modified) response.

If the differences are only those you've listed above why not link to
the HTTP definitions without redefining something already defined?

A.

---

From: Klaus Hartke <[email-masked]>
Date: Fri, 26 Nov 2010 16:52:46 +0100

> the HTTP definitions without redefining something already defined?

So you'd suggest that CoAP method codes and options should be defined
also just in terms of differences to their respective HTTP
counterparts?

Klaus

---

From: "Angelo P. Castellani" <[email-masked]>
Date: Fri, 26 Nov 2010 16:58:21 +0100

Yes.

HTTP can be used as a reference, and we can explicitly tell when the
HTTP definition isn't good for CoAP and clearly describe only the
peculiarities/differences/new behaviours.

---

From: Klaus Hartke <[email-masked]>
Date: Fri, 26 Nov 2010 17:17:15 +0100

Angelo P. Castellani wrote:
>> [define the protocol in terms of differences to HTTP]
>
> Yes.
>

Let's change the name to "Minified HTTP" then, so people don't get the
wrong impression we're creating a new protocol here.

Klaus

---

From: Linyi Tian <[email-masked]>
Date: Sat, 27 Nov 2010 10:45:35 +0800

In general I agree with Angelo we can just refer to the same definition for
status code from HTTP. If there is difference we should clearly describe the
difference and why. 

We talked about the new codes defined by CoAP but we didn't discuss what
code will not be used by CoAP, right? Since CoAP is for constrained devices
and not for web, some status code may not be appropriate for CoAP. This
should be described as well in our draft. Otherwise people may wondering
whether this code can be used or not which will lead to interoperable
problem as well.

The section 4 in [HTTP 1.1 Part 2] is very helpful. It has the Status Code
and Reason Phrase. We may need the same table as follows (just an example):
Status-Code =
/ "200" ; [HTTP 1.1 Part2] Section 8.2.1: OK
/ "201" ; [HTTP 1.1 Part2] Section 8.2.2: Created
...........
/ "505" ; [HTTP 1.1 Part2] Section 8.5.6: HTTP Version not supported (not
used by CoAP)
/ "xxx" ; [Link Format] Section x.x.x: xxxxxx [Defined by CoAP] 

Cheers,
Linyi

>>-----Original Message-----
>>From: [email-masked] [mailto:[email-masked]] On Behalf Of
>>Klaus Hartke
>>Sent: Saturday, November 27, 2010 12:17 AM
>>To: [email-masked]
>>Subject: Re: [core] coap #77 (new): Response code semantics
>>

[Linyi Tian] Do you mean you will change the "CoAP" to "Minified HTTP"?

---

From: Klaus Hartke <[email-masked]>
Date: Sat, 27 Nov 2010 22:25:09 +0100

Linyi Tian wrote:
> Do you mean you will change the "CoAP" to "Minified HTTP"?

Only if we change the whole protocol to be defined in differences to
HTTP. However, it was agreed on a long time ago that CoAP is a new
protocol  inspired by REST, which is easily mappable to HTTP, but not
just "compressed" HTTP. So, no, we won't change the name, and we won't
define CoAP in differences to HTTP. (References to HTTP are, of
course, perfectly valid.)

Klaus

---

From: "Angelo P. Castellani" <[email-masked]>
Date: Mon, 29 Nov 2010 08:58:44 +0100

On Sat, Nov 27, 2010 at 22:25, Klaus Hartke <[email-masked]> wrote:
> However, it was agreed on a long time ago that CoAP is a new
> just "compressed" HTTP.

Definitions borrowed from HTTP, doesn't belong to CoAP.

GET, POST, PUT, DELETE... 200 OK, 100 Continue, 404 Resource not
found, etc. etc.

This is HTTP, there is no "new protocol" here in these definitions.

To highlight the *novelty* in the CoAP protocol, reasoned differences
from HTTP make much more sense.

Redefining with some minor difference, is not "creating a new protocol"

On Sat, Nov 27, 2010 at 22:25, Klaus Hartke <[email-masked]> wrote:
> So, no, we won't change the name, and we won't
> define CoAP in differences to HTTP.

Why talk on the ML if you already know what will be done? Isn't this a
working group?

Regards,
Angelo

---

From: Zach Shelby <[email-masked]>
Date: Mon, 29 Nov 2010 10:43:03 +0200

Hi,

I don't understand exactly what you guys are debating about here. The CoAP specification is already in pretty good shape, and we have found a reasonable balance between being a new protocol and re-using HTTP methods and codes. As Klaus mentioned, already long ago we decided against calling this some kind of HTTP "light". Let's not waste energy on that.

You started out by debating what should be included in the Annex on response codes. A ticket was made to better define (there is just a table right now) the semantics of response codes. That is, how much text should we write about each response code. I think the answer to that is pretty simple: We make a sub-section for each response code. If the semantic is exactly the same as in RFC2616, then just reference. If there are some small differences, then explain them. OK?

Zach

-- 
Zach Shelby, Chief Nerd, Sensinode Ltd.
http://zachshelby.org  - My blog "On the Internet of Things"
http://6lowpan.net - My book "6LoWPAN: The Wireless Embedded Internet"
Mobile: +358 40 7796297

---

From: tianlinyi 00175029 <[email-masked]>
Date: Mon, 29 Nov 2010 16:53:24 +0800

Hi, Zach and all

I agree with Zach. However you missed one point i made:
If we list all codes from HTTP, we'd better describe some codes are not used by CoAP. If we just list part of them, then Zach's suggestion would be fine.

Cheers,
Linyi

----- 原邮件 -----
发件人: Zach Shelby <[email-masked]>
日期: 星期一, 十一月 29日, 2010 下午4:43
主题: Re: [core] coap #77 (new): Response code semantics
收件人: "Angelo P. Castellani" <[email-masked]>
抄送: [email-masked], Klaus Hartke <[email-masked]>

> Hi,
> 
> I don't understand exactly what you guys are debating about here. 
> The CoAP specification is already in pretty good shape, and we 
> have found a reasonable balance between being a new protocol and 
> re-using HTTP methods and codes. As Klaus mentioned, already long 
> ago we decided against calling this some kind of HTTP "light". 
> Let's not waste energy on that.
> 
> You started out by debating what should be included in the Annex 
> on response codes. A ticket was made to better define (there is 
> just a table right now) the semantics of response codes. That is, 
> how much text should we write about each response code. I think 
> the answer to that is pretty simple: We make a sub-section for 
> each response code. If the semantic is exactly the same as in 
> RFC2616, then just reference. If there are some small differences, 
> then explain them. OK?
> 
> Zach
> 
> > To highlight the *novelty* in the CoAP protocol, reasoned 
> differences> from HTTP make much more sense.
> > 
> > Redefining with some minor difference, is not "creating a new 
> protocol">

---

From: Zach Shelby <[email-masked]>
Date: Mon, 29 Nov 2010 10:59:34 +0200

> If we list all codes from HTTP, we'd better describe some codes are not used by CoAP. If we just list part of them, then Zach's suggestion would be fine.

Good point. The intention is that only the codes Table 3 of Section 11.1 are used by CoAP. A sub-section is planned for each code according to this ticket.

http://tools.ietf.org/html/draft-ietf-core-coap-03#section-11.1

We should also add a reference column to this table.

Zach

---

From: "Angelo P. Castellani" <[email-masked]>
Date: Mon, 29 Nov 2010 10:00:07 +0100

Thanks Zach,
defining the differences and referencing is the best solution in my opinion too.

Angelo

---

From: Salvatore Loreto <[email-masked]>
Date: Mon, 29 Nov 2010 11:24:56 +0200

> defining the differences and referencing is the best solution in my opinion too.

+1

/Sal

> Angelo
>
> On Monday, November 29, 2010, Zach Shelby<[email-masked]>  wrote:
>> Hi,
>>
>>> On Sat, Nov 27, 2010 at 22:25, Klaus Hartke<[email-masked]>  wrote:
>>> On Sat, Nov 27, 2010 at 22:25, Klaus Hartke<[email-masked]>  wrote:

-- 
Salvatore Loreto
www.sloreto.com

---

From: [email-masked]
Date: Mon, 29 Nov 2010 11:18:25 +0100

Zach,

>The intention is that only the codes Table 3 of Section 11.1 are used by
CoAP. A sub-section is planned for each code according to this ticket.
http://tools.ietf.org/html/draft-ietf-core-coap-03#section-11.1
We should also add a reference column to this table.

Personnaly, I find a bit confusing the fact that CoAP specification uses
HTTP status code to describe its own behaviour because actually it is not
the real code that is sent/received and sometimes there are differences
with HTTP.

I would prefer the text
2.3.1.  GET
   The GET method retrieves the information of the resource identified
   by the request URI.  Upon success a 200 (OK) response SHOULD be sent.

defined like that
2.3.1.  GET
   The GET method retrieves the information of the resource identified
   by the request URI.  Upon success a SUC_OK response SHOULD be sent.

and then define Table 3 of Section 11.1 like that
+-------------+------+------------------+----------------------+
| Class       | Code | CoAP Label       | HTTP Name            |
+-------------+------+------------------+----------------------+
| Success     | 0x20 | SUC_OK           | 200 OK (*)           |
| ...         | ...  | ...              | ...                  |
| Redirection | 0x40 | RED_NOT_MODIFIED | 304 Not modified (*) |
| ...         | ...  | ...              | ...                  |
| Errror      | 0x60 | ERR_BAD_REQUEST  | 400 Bad Request      |
| ...         | ...  | ...              | ...                  |

(*) means the conversion is not necessarily straightforward

Then explain the differences for each (*) in a section:
Example: SUC_OK not supported for POST in CoAP

I find it easier that way to optimize the extraction of a class of codes
and to introduce differences with HTTP or new codes.
Does it make sense ?

Matthieu

---

From: Zach Shelby <[email-masked]>
Date: Mon, 29 Nov 2010 13:19:47 +0200

I like this proposal, and have noticed quite a few people confused by the current use of e.g. 200 (OK) in the text. 

Zach

On Nov 29, 2010, at 12:18 PM, [email-masked] wrote:

> Zach,
> 
> >The intention is that only the codes Table 3 of Section 11.1 are used by CoAP. A sub-section is planned for each code according to this ticket.
> Personnaly, I find a bit confusing the fact that CoAP specification uses HTTP status code to describe its own behaviour because actually it is not the real code that is sent/received and sometimes there are differences with HTTP.
> 
> I would prefer the text
> 2.3.1. GET
> I find it easier that way to optimize the extraction of a class of codes and to introduce differences with HTTP or new codes.
> Does it make sense ?
> 
> Matthieu
>