Re: HTTP Response Codes - Just for clarity

On Wed Nov 12 2014 at 4:42:19 AM James Graham <james@hoppipolla.co.uk>
wrote:

> On 12/11/14 00:03, Jason Leyba wrote:
> > Inline.
> >
> > On Tue Nov 11 2014 at 3:52:59 PM David Burns <dburns@mozilla.com
> > <mailto:dburns@mozilla.com>> wrote:
> >
> >     Answers inline
> >
> >     On 10/11/2014 09:51, James Graham wrote:
> >     > On 08/11/14 00:44, David Burns wrote:
> >     >> Hi All,
> >     >>
> >     >> I have started going through the notes and making some of the
> changes
> >     >> and am looking at HTTP Response codes that should be returned. I
> have
> >     >> put examples below, can you check that I am understanding
> correctly
> >     >> before I carry on. This is only a subset but it covers most of
> >     the URL
> >     >> endpoint types
> >     >>
> >     >> GET /session/{sessionId}/element/{__ELEMENT}/attribute/{name}
> >     >>    200 if the attribute found
> >     >>    404 if not found with data being returned as {"value": null}
> >     > I'm not sure why this would be {"value":null}; I thought the plan
> was
> >     > for all non-200 responses to have {"error":something} in the body.
> >
> >     I was trying to show that if we don't find the attribute/property
> name
> >     we return a 404. The spec describes that if we can't find the
> >     attribute/property we need to return a null. I am happy to have that
> >     localends just infer that when they get back a 404 that it is the
> >     equivalent to a null.
> >
> >
> > HTTP 404 implies an error. If we go this route (and I don't think we
> > should), we should use a 204.
>
> If you don't want to model the attribute a a REST resource then don't,
> but if you do — and the design above does — a 404 is clearly the right
> response code for cases where the resource isn't found.
>
> Of course the local end can expose that 404 in any way it likes e.g.
> returning null/None, raising an AttributeNotFound exception, etc.
>
> >     >> POST /session/{sessionId}/element/
> >     >>    200 if Element is found
> >     >>    501 if it is not found with error in data model returned
> >     > Assuming you mean this as an example of a method/path combo that
> >     doesn't
> >     > exist, 404 seems more appropriate (and 405 if the path exists but
> the
> >     > wrong method was used).
> >
> >     Yea, we should be returning 405 if we expect a GET and get a POST or
> >     <insert other verb here>.
> >     What should we return if the URL and verb used are correct but the
> >     element is not found?
>
> I still don't see POST /session/{sessionId}/element/ in the spec. I see
> various GET /session/{sessionId}/element/{elementId}/{something}
> commands which should return a 404 if the element isn't found.
>
> >     200 with current status (kinda like what we do oyrselves
> >
> >
> > We shouldn't use HTTP codes for command results - we'll lose the ability
> > to return errors about the request.  Stick to convention on response
> codes:
> >
> > 5xx: server failed to process the request
> > 4xx: invalid request (404 - session/element id not found, 405 method not
> > permitted, etc.)
> > 2xx: valid request & command executed successfully, see body for result
>
> I can't tell whether I agree with this, but I don't see any reason why
> we can't send a response body containing error details with non-2xx
> responses (indeed it seems to be a SHOULD-level requirement in HTTP). So
> I'm not sure I see what ability you are worried about losing.
>
>
Suppose we use REST and you request an element attribute:

GET /session/{sessionId}/element/{ELEMENT}/attribute/{name}

You get back a 404. What does the 404 apply to? {sessionId}, {ELEMENT}, or
{name}? In terms of the existing client APIs [1], the first two would be
errors, but the third would be permissible. So how do you differentiate -
put the details in the response body?

{"status": "session not found"}
{"status": "element not found"}
{"status": "success", "value": "null}

Now returning the 404 is redundant with the information in the response
body.

-- Jason

[1] I suppose someone could implement a client API that considered a
missing attribute as an error.