[Draft ] HTTP status codes issue resolution for API spec

All,


This is the draft of the email I plan to send to Yves and Philippe as 
the resolution of issue on the HTTP status codes in the API spec.

We can discuss it during the telecon.

Thierry



---------------------------


Yes, Philippe,

This is our follow up on the HTTP status codes issue raised during the 
Transition call of the API spec to CR.

The MAWG has discussed this issue and we have come up with a proposal:
First let me clarify our analysis:

1- We are not using these status codes as return values of an HTTP 
request, but as a status in the methods of our API. We think this makes 
a difference.


2- We had a look at the Webdav spec. WebDAV is an example that defines 
new status codes beyond those of the original HTTP 1.1 spec (e.g. 507 in 
[1]).

RFC 2616 states in section 1.1:
"HTTP status codes are extensible. HTTP applications are not required
    to understand the meaning of all registered status codes, though such
    understanding is obviously desirable. However, applications MUST
    understand the class of any status code, as indicated by the first
    digit, and treat any unrecognized response as being equivalent to the
    x00 status code of that class, with the exception that an
    unrecognized response MUST NOT be cached. For example, if an
    unrecognized status code of 431 is received by the client, it can
    safely assume that there was something wrong with its request and
    treat the response as if it had received a 400 status code. In such
    cases, user agents SHOULD present to the user the entity returned
    with the response, since that entity is likely to include human-
    readable information which will explain the unusual status."

--> We think that our extension would confirm to this even if it was a 
real response to an HTTP  request. As it is *not an HTTP response*, the 
issue is even less critical in the group's opinion.

RESOLUTION:

We have added the following statement in the API specification [2]

[
This section introduces a set of status codes for the defined API to 
indicate the system behavior. As described in section 4.4, the status 
code is returned as one of the attributes of the Media Annotation object 
returned by a method call to the API.

The status codes follow the scheme of the HTTP/1.1 [HTTP11] status 
codes, because developers are familiar with it. This choice does not 
imply any specific link with HTTP, nor are the status codes used as part 
of the actual HTTP response. Status codes from HTTP/1.1 are used with 
the same semantics as in [HTTP11] whenever possible, adding specific 
codes when needed. These specific codes are extensions in conformance 
with section 6.1 of [HTTP11].
]



Yves and Philippe could you please confirm that you agree to our 
resolution. Then we will proceed to Transition to CR.

Best,

Thierry






[1] https://tools.ietf.org/html/rfc4918#section-9.3.1

[2] 
http://www.w3.org/2008/WebVideo/Annotations/drafts/API10/CR/Overview.html#api-status-codes

Received on Tuesday, 11 October 2011 08:46:22 UTC