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

Yves,

Please find bellow the responses to the points you raised in your last 
email about the HTTP status codes for API

We are trying to get a resolution here to move our API spec forward.
If you need more discussion we can trigger a special telecon to nail 
this down ASAP.

Thierry.


-------- Message original --------
Sujet: AW: follow up on the HTTP status codes for API spec to CR.
Date : Wed, 12 Oct 2011 13:53:35 +0200
De : Bailer, Werner <werner.bailer@joanneum.at>
Pour : tmichel@w3.org <tmichel@w3.org>,        Florian Stegmaier 
<stegmai@dimis.fim.uni-passau.de>
Copie ŕ : public-media-annotation@w3.org <public-media-annotation@w3.org>

Hi Thierry,

I just had a phone call with Florian to discuss this issue. There are 
basically two points in Yves mail, please find our draft responses to 
these points below.

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).

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.



[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
> >>
> >

Received on Wednesday, 12 October 2011 14:44:28 UTC