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

Hi Yves, 

please find my answers inline.

> -----Ursprüngliche Nachricht-----
> Von: public-media-annotation-request@w3.org [mailto:public-media-
> annotation-request@w3.org] Im Auftrag von Yves Lafon
> Gesendet: Mittwoch, 12. Oktober 2011 18:23
> An: Thierry MICHEL
> Cc: Philippe Le Hegaret; public-media-annotation@w3.org
> Betreff: Re: 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?

The return code is 200 in this case, as a server-side implementation does return a complete data structure. This is in analogy to a client side implementation, where you do not get an exception, but a also a return data structure, containing among others the status 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)

The API spec does not define what happens in the implementation, an implementation could either do everything locally, or call a server over HTTP.

I hope this helps to clarify the issue.

Best regards,
Werner

> > [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 Thursday, 13 October 2011 07:17:23 UTC