Re: Fwd: AW: follow up on the HTTP status codes for API spec to CR.

On Wed, 12 Oct 2011, Thierry MICHEL wrote:

> 1. 4xx instead of 5xx
>
> RFC 2616 defines:
>     - 4xx: Client Error - The request contains bad syntax or cannot be 
> fulfilled
>     - 5xx: Server Error - The server failed to fulfill an apparently valid 
> request
>
> The issue of a property not implemented (our proposed 562) is caused on the 
> API ("server") side, and occurs when the request (method call) is valid. Thus 
> we think that it is justified to be a 5xx error (a more specific case than 
> the general 501 not implement, which we used before, and which was criticized 
> by the submitter of the LC comment)[1].
>
> Also, it is different to our proposed 462, which is in fact the response of a 
> request for a property that does not exist in the metadata of the media 
> resource (though the implementation would be able to return it).

Hum, ok, so it clarifies something that was not really clear, that it is 
about server code implementing the extraction of the property instead of 
the property being absent from the resource.

Still, one question stands, what is the HTTP return code in that case? (as 
this code is from your definition not an HTTP response code). 200 OK?
Or a HTTP 501 that contains in the body a finer-grained explanation via 
the 562 code?

> 2. Why doing this tunneling instead of reusing the HTTP response code?
>
> Our API is designed to be used both in server- and client side 
> implementations. In the latter case, a request to the API is calling a 
> JavaScript method, i.e., there is no HTTP request/response involved. Thus a 
> kind of tunneling also occurs when calling API methods on the server side 
> over HTTP. Directly returning the response code (and not as part of the 
> return data structure) would make the API definitions for the client- and 
> server side implementation incompatible.

So you mean that client-side implementations are calling js but that js 
code is not calling anything using HTTP, so does everyting locally? Or 
does this mean that you are abstracting from what happens under that JS 
API (like... tunneling over HTTP)

> [1] http://www.w3.org/2006/02/lc-comments-tracker/42786/WD-mediaont-api-
> 1.0-20100608/2556?cid=2556
>
> Best regards,
> Werner
>
>> -----Ursprüngliche Nachricht-----
>> Von: Thierry MICHEL [mailto:tmichel@w3.org]
>> Gesendet: Mittwoch, 12. Oktober 2011 09:11
>> An: Florian Stegmaier
>> Cc: Bailer, Werner; public-media-annotation@w3.org
>> Betreff: Re: follow up on the HTTP status codes for API spec to CR.
>> 
>> Florian, Werner,
>> 
>> Could you please advocate our response to Yves (or maybe adopt his
>> proposal)
>> 5XX to a request from the client that should trigger a 4XX (missing
>> _requested_ property).
>> 
>> 
>> We have to move this issue forward, according to the Last Call comment
>> http://www.w3.org/2006/02/lc-comments-tracker/42786/WD-mediaont-api-
>> 1.0-20100608/2556?cid=2556
>> 
>> Thierry
>>
>>  >
>> 
>> Le 11/10/2011 17:04, Yves Lafon a écrit :
>> > On Tue, 11 Oct 2011, Thierry MICHEL wrote:
>> >
>> >> Yves, 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.
>> >
>> > Ok, so it means that you are tunnelling pseudo-http over htt, or
>> > partially subverting real HTTP codes with your in-object status.
>> >
>> >> 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 6.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.
>> >
>> > Well, in your case, the WG decided to respond with a 5XX to a request
>> > from the client that should trigger a 4XX (missing _requested_ property).
>> >
>> >>
>> >> 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.
>> >
>> > Why doing this tunnelling instead of reusing the HTTP response code?
>> >
>> >> 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
>> >>
>> >
>

-- 
Baroula que barouleras, au tiéu toujou t'entourneras.

         ~~Yves

Received on Wednesday, 12 October 2011 16:22:36 UTC