HTTP status code table in 0.8.1 docs

[Arne Roomann-Kurrik (Google)]

For the the 0.8.1 RESTful/RPC protocl spec documentation, it would be
useful to put in a HTTP status table similar to the following:
http://code.google.com/apis/gdata/reference.html#http-status-codes

This proposal is to use the following in the spec documentation:

400 BAD REQUEST
Invalid request URI or header, or unsupported nonstandard parameter.

401 UNAUTHORIZED
Authorization required.

403 FORBIDDEN
Authentication or authorization failed. Request is not allowed by the
current auth context.

404 NOT FOUND
Resource (such as a feed or entry) not found.

501 NOT_IMPLEMENTED
The request was valid but had not been implemented by the provider
yet. It will be implemented later.

500 INTERNAL SERVER ERROR
Internal error. This is the default code that is used for all
unrecognized errors.

417 EXPECTATION_FAILED
Usually used for a limit exceeded error. See the error message for
more information.

Does anyone have any problems with these values/definitions?

[Scott Seely]

417 is for when an Expect header couldn't be satisfied. What part of
OpenSocial mandates the use of the HTTP Expect header? (I'll grant that
I may have read the specs too quickly.) So, no to 417.

501 does not imply an intent to later implement a feature. 501
explicitly states:

10.5.2 501 Not Implemented

The server does not support the functionality required to fulfill the
request. This is the appropriate response when the server does not
recognize the request method and is not capable of supporting it for
any resource.

I'm OK with using 501, but I don't want the usage in OpenSocial to imply
that one intends to implement the feature eventually. This is only a
statement that "this endpoint doesn't do that yet."

I'd also like to see these:

10.4.6 405 Method Not Allowed
The method specified in the Request-Line is not allowed for the
resource identified by the Request-URI. The response MUST include an
Allow header containing a list of valid methods for the requested
resource.

Example: 405 is needed when trying to do anything other than a GET
against @supportedFields.

10.4.10 409 Conflict

The request could not be completed due to a conflict with the current
state of the resource. This code is only allowed in situations where
it is expected that the user might be able to resolve the conflict
and resubmit the request. The response body SHOULD include enough
information for the user to recognize the source of the conflict.
Ideally, the response entity would include enough information for the
user or user agent to fix the problem; however, that might not be
possible and is not required.

Conflicts are most likely to occur in response to a PUT request. For
example, if versioning were being used and the entity being PUT
included changes to a resource which conflict with those made by an
earlier (third-party) request, the server might use the 409 response
to indicate that it can't complete the request. In this case, the
response entity would likely contain a list of the differences
between the two versions in a format defined by the response
Content-Type.

Example: 409 would be required to handle conflicting updates to a
resource.

Other standard codes that we need to use:
200 OK: Operation was successful.
201 Created: Used when an entity was created (via a POST or PUT)
204 No Content: Indicates everything worked and the server is not
sending back any actual data.

[Arne Roomann-Kurrik]

These make sense.  Do you have a suggestion on what is to be returned for limit exceeded errors?

~Arne

--
OpenSocial IRC - irc://irc.freenode.net/opensocial

[Scott Seely]

Limit exceeded sounds like 403: Forbidden.

 

“403 Forbidden

 

   The server understood the request, but is refusing to fulfill it.

   Authorization will not help and the request SHOULD NOT be repeated.

   If the request method was not HEAD and the server wishes to make

   public why the request has not been fulfilled, it SHOULD describe the

   reason for the refusal in the entity.  If the server does not wish to

   make this information available to the client, the status code 404

   (Not Found) can be used instead.”

 

409 may be more appropriate as the user can resolve the conflict and resubmit the request by removing some of their ‘stuff’.

 

I could see arguing for both of these. The interesting part is the entity body that describes why the 403/409 was returned.

 

 

 

Scott Seely

architect

email  sse...@myspace.com

[Cassie]

+1 for 409 that way users can easily distinguish between being actually forbidden and just needing to deal with a limit exceeded error (ie by deleting content).

- Cassie

[Louis Ryan]

I worry a little bit about using 409 when we have alignment with PortableContacts where there is clear intent to do lots of syncing and therefore a greater potential for true conflict handling. I must admit I have no idea about the practicalities of using sub-codes in the wild so Im hesitant to suggest it even if it seems like the right thing to do.

I would be completely fine if we standardize the message bodies of the responses and allow for status code overlap. This may be the most transparent approach.

[Scott Seely]

Sub codes are used fairly extensively in the IIS/ASP.NET ecosystem and it all seems to work quite well. I have no idea how well the rest of the world handles this.

[Louis Ryan]

In Java land they're not used at all

HttpServletResponse.setStatus(int)

doesn't really allow for it...

Seems like we should just standardize the error messages ?

[Cassie]

Hey guys - we should try to close this out. From Arne's first post all we need to do right now are agree on some standard error codes for the server apis. This doesn't need to include every error code in the world as containers should be free to return additional codes as they need to.

I think we should delay the sub code/error message to 0.9 or something so we can just wrap this smaller part up for 0.8.1

From the first post these codes seem fine:
400 BAD REQUEST
401 UNAUTHORIZED
403 FORBIDDEN
404 NOT FOUND
501 NOT_IMPLEMENTED (as long as we make a slight fix to the wording here)
500 INTERNAL SERVER ERROR


This one needs a different http error code instead of 417. One suggessted option was 409 (or 403 but that is sorta taken already)
409 Limit Exceeded

And these two codes were proposed in addition to the ones defined above:
405 Method Not Allowed
409 Conflict


So, if we add the two new codes and change the limit exceeded error to be 409 will that work for everyone?

Thanks!

- Cassie

[Scott Seely]

Cassie,

This list looks correct. Can you put up the proposed wording change so that we can have an informed vote on this?

Thanks!

[Cassie]

Sure:

400 BAD REQUEST
Invalid request URI or header, or unsupported nonstandard parameter.

401 UNAUTHORIZED
Authorization required.

403 FORBIDDEN
Authentication or authorization failed. Request is not allowed by the
current auth context.

404 NOT FOUND
Resource (such as a feed or entry) not found.

405 METHOD NOT ALLOWED
The method called on the uri is not allowed. (For example a POST on /people/@supportedFields)

409 CONFLICT
Can be used for a limit exceeded error as well as conflicting updates. See the error message for
more information.

501 NOT_IMPLEMENTED
The request was valid but has not been implemented by the provider
yet.

500 INTERNAL SERVER ERROR
Internal error. This is the default code that is used for all
unrecognized errors.

[Arne Roomann-Kurrik]

+1

[Scott Seely]

I think that we need to provide additional behavior MUSTs when returning some of these codes. Here is a proposal for the DL to beat up. The text reflects what I think we will have to implement to have some consistency in these status codes across OpenSocial sites.

HTTP Status Codes

400 BAD REQUEST

OpenSocial application servers MUST return 400 BAD REQUEST under any one or more of the following conditions:

·         Invalid request URI

·         Invalid HTTP Header

·         Receiving an unsupported, nonstandard parameter

·         Receiving an invalid HTTP Message Body

401 UNAUTHORIZED

OpenSocial container servers MUST return 401 UNAUTHORIZED when receiving a request for a protected resource and the request is either

·         Missing OAuth authorization credentials as described in OAuth Consumer Request 1.0, http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/1/spec.html.

·         OAuth authorization credentials are present, but the user identity is not authorized to access the protected resource.

If the request already included authorization credentials, the 401 response indicates that the request has been refused for those credentials. A 401 response MUST include a WWW-Authenticate header field indicating the request MAY present an OAuth token for the container server’s realm. Example:

WWW-Authenticate: OAuth realm="http://sp.example.com/"

 

[Editor’s note: RFC 2616 indicates that a 401 MUST include a WWW-Authenticate header field. OAuth 1.0, section 5.4.2 indicates that the WWW-Authenticate header with OAuth as a challenge is optional. With OAuth being required, we need to require this response in order to stay in line with RFC 2616 and HTTP Status Code 401.]

403 FORBIDDEN

The server understood the request but is refusing to fulfill it. Authorization will not help. The current authorization context does not allow the request.

404 NOT FOUND

The server has not found a resource (such as a feed or entry) that matches the request URI.

405 METHOD NOT ALLOWED

The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response MUST include an Allow header containing a list of valid methods for the requested resource.

[Editor’s note: I am not inventing new requirements here. RFC 2616 indicates that a 405 MUST include an Allow header field. Actually, the above text is verbatim from RFC 2616.]

409 CONFLICT

The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required.

 

Conflicts are most likely to occur in response to a PUT request. For example, this code can be used for a limit exceeded error as well as conflicting updates. See the error message for more information.

[Editor’s note: I am not inventing new requirements here. The above text is mostly verbatim from RFC 2616.]

500 INTERNAL SERVER ERROR

Internal error. This is the default code that is used for all unrecognized errors.

501 NOT IMPLEMENTED

The request was valid but has not been implemented by the provider. A container SHOULD return 501 NOT IMPLEMENTED when receiving a request for an OPTIONAL/MAY feature that the container does not implement.

[scottk]

Any votes or other replies to Scott's proposal of additional details
to the table of status codes?

Thanks,
ScottK

On Sep 18, 11:36 am, Scott Seely <SSe...@myspace.com> wrote:
> I think that we need to provide additional behavior MUSTs when returning
> some of these codes. Here is a proposal for the DL to beat up. The text
> reflects what I think we will have to implement to have some consistency
> in these status codes across OpenSocial sites.
>
> HTTP Status Codes
>
> 400 BAD REQUEST
>
> OpenSocial application servers MUST return 400 BAD REQUEST under any one
> or more of the following conditions:
>

> *         Invalid request URI
>
> *         Invalid HTTP Header
>
> *         Receiving an unsupported, nonstandard parameter
>
> *         Receiving an invalid HTTP Message Body

>
> 401 UNAUTHORIZED
>
> OpenSocial container servers MUST return 401 UNAUTHORIZED when receiving
> a request for a protected resource and the request is either
>

> *         Missing OAuth authorization credentials as described in OAuth

> Consumer Request 1.0,http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/1/s
> pec.html.
>

> *         OAuth authorization credentials are present, but the user

> 10.5.2 ...
>
> read more »

[Cassie]

Overall, I think Scott's proposal is a little detailed for this stage in the game. (I think we could wait until 0.9 to be very specific on each error code) However, it sounds fine to me.

+1

[Scott Seely]

+1 (naturally)

[Dan Peterson]

I agree that standard error codes are better than no error codes, so +1

Looks like we need 2 more?

I believe this is the last gating issue for 0.8.1, so please speak up,

-Dan

[Dan Peterson]

I agree that standard error codes are better than no error codes, so +1

Looks like we need 2 more?

I believe this is the last gating issue for 0.8.1, so please speak up,

-Dan

[Chad Russell]

+1

---

From: opensocial-an...@googlegroups.com on behalf of Dan Peterson
Sent: Mon 9/22/2008 5:10 PM

[Arne Roomann-Kurrik]

+1 

~Arne

[Maxwell Newbould]

+1

[scottk]

OK, I'll go ahead and add these to the doc.

Dan -- what are the "2 more" you referred to?

Thanks,
Scott

On Sep 23, 10:19 am, Maxwell Newbould <mnewbo...@myspace.com> wrote:
> +1
>
> From: opensocial-an...@googlegroups.com
> [mailto:opensocial-an...@googlegroups.com] On Behalf Of Arne
> Roomann-Kurrik
> Sent: Monday, September 22, 2008 6:38 PM
> To: opensocial-an...@googlegroups.com
> Subject: [opensocial-and-gadgets-spec] Re: HTTP status code table in
> 0.8.1 docs
>
> +1  
>
> ~Arne
>

> On Mon, Sep 22, 2008 at 6:12 PM, Chad Russell <cruss...@myspace.com>

> <http://asp.net/>  ecosystem and

>
>
>
> > it all seems to work quite well. I have no idea how well the rest of
> the
> > world handles this.
>
> > Scott Seely
>
> > architect
>
> > email  sse...@myspace.com
>
> > From: opensocial-an...@googlegroups.com
> > [mailto:opensocial-an...@googlegroups.com] On Behalf Of
> Louis
> > Ryan
> > Sent: Friday, September 12, 2008 10:04 AM
>
> > To: opensocial-an...@googlegroups.com
>
> > Cc: Joseph Smarr
> > Subject: [opensocial-and-gadgets-spec] Re: HTTP status code table in
> > 0.8.1 docs
>
> > I worry a little bit about using 409 when we have alignment with
> > PortableContacts where there is clear intent to do lots of syncing and
> > therefore a greater potential for true conflict handling. I must admit
> I
> > have no idea about the practicalities of using sub-codes in the wild
> so
> > Im hesitant to suggest it even if it seems like the right thing to do.
>
> > I would be completely fine if we
>

> ...
>
> read more »

[Dan Peterson]

Just meant 2 more votes, and I saw at least 3 more :)

[scottk]

Got it. I thought you meant 2 more error codes... :)

Thanks,
ScottK

> ...
>
> read more »