RE: [Draft ] HTTP status codes issue resolution for API spec

Thierry,

in point 2, it should say "RFC 2616 states in section 6.1" (I made a typo in my previous mail).

Best regards,
Werner

> -----Original Message-----
> From: public-media-annotation-request@w3.org [mailto:public-media-
> annotation-request@w3.org] On Behalf Of Thierry MICHEL
> Sent: Dienstag, 11. Oktober 2011 10:46
> To: public-media-annotation@w3.org
> Subject: [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.ht
> ml#api-status-codes

Received on Tuesday, 11 October 2011 10:51:27 UTC