[openstack-qa] Return codes for OpenStack APIs

Attila Fazekas afazekas at redhat.com
Fri Feb 1 09:45:40 UTC 2013


OK. 

In this case a server create request is casing two operation:
 - creating the object(s) (201)
 - async status change request (202).  We got the status code of this operation.

Mixing sync and async operation in single REST request is not the cleanest REST solution.
We can say, it is just the create operation and response with 201. And let say the async operation started _later_ because of an internal behavior.  

http status codes are not "equals" to a C return value.
Every 2xx can be translated to EXIT_SUCCESS, 'return 0;'

The xx part just tells some additional information.

Any of 200,201,202 are good status code in a successful create response.
Any of 200,202,204 are good status code in a successful delete response.

I do not think we must promise an async delete never will be sync, by specifying exactly 202 in the documentation.

The cinder have very similar architecture as nova:  api->sch->action(cpu,vol)
But it gives back 200 on volume creation.

The 200 is OK based HTTP spec, but we can tell more about the happenings by a 201.
Let's say it is like a too short commit message :)

So a pedantic HTTP REST implementation, should not response just with 200 on create/delete.

The 4xx (and 5xx) are very very different topic:
 In this case not just the error code, but the situation which causes it should be documented.
For example: 

<foo> create duplicate:
409: You attempted to create a <foo>, but <foo> already exists with <bar> name.

404 in delete context:
- 404: You tried to delete a not existing <foo>.
       You can run into this error even when you dose not have permissions work with <foo>, because <foo> is in a different tenant.


The 5xx are server errors:
  Their meaning generally service scoped.
   Does not need to be documented for every REST action. 


I would recommend to be pedantic and do not use 200 in create/delete responses, and do not mix sync and async operation on behalf of a single request.
I do not recommend to promise something will be async forever by a documenting an exact 202 code and vice versa.


PS.:
202 is the good response when we request a change and we are not able to see it in an immediate subsequent query.
The OS state change request changes status immediately to <foo>ing, and it is visible in subsequent request, 
so the 200 would be more correct. These actions are committing something to database, as the result of the request.    
IMHO even our async operations closer to the sync behavior in the HTTP REST perspective.


Just IMHO.



----- Original Message -----
From: "Sean Dague" <sdague at linux.vnet.ibm.com>
To: openstack-qa at lists.openstack.org
Sent: Thursday, January 31, 2013 8:41:18 PM
Subject: Re: [openstack-qa] Return codes for OpenStack APIs

The general concensus in Nova is that 202 is the right code for an async 
operation. The biggest issue is that it's not actually consistent. 
However changing returns codes is a contract break.

The Nova v3 API is largely about fixing this, and will be in Havana 
(probably by H-1).

	-Sean

On 01/31/2013 12:14 PM, Attila Fazekas wrote:
>
> I see lot of inconsistency about 200 and 202 or 201 usage in the openstack component.
>
> 200: Can be a good in any OK situation, generally good  answering GET requests (list or individual entity get).
>
> 201: Can be a good response, when the object created , like a new user entry.
> 202: Can be a good response, when the resource promised to be created (volume, server)
>
> I am not sure we had to accept the current response codes as standard behavior.
> I am not sure we need to document the current behavior as future standard.
>
> I think we should have this response __consistent__ across all open-stack component.
>
> IMHO 201 or 202 is not something the API need to grantee. It is something what the server implementation can promise at the current situation.
>
> When nova says 202, the instance is not started at the moment, but will be started, however the object is exists in the DB.
>
> Do we consider the new server/volume entry as new existing object when it is in a "creating" status ?
> If yes. The 202 is not fully correct IMHO. The 201 would be better.
>
> I think the 201 describes best the successful create in the OpenStack component.
>
>
> ----- Original Message -----
> From: "Sam Danes" <sam.danes at RACKSPACE.COM>
> To: openstack-qa at lists.openstack.org
> Sent: Thursday, January 31, 2013 4:45:29 PM
> Subject: Re: [openstack-qa] Return codes for OpenStack APIs
>
> This sounds like a good plan David. If the docs are ambiguous or outright missing info, we should file the doc bug too. I think we all agree that the checking for Nxx codes is a bad test. :-)
>
> -----Original Message-----
> From: David Kranz [mailto:david.kranz at qrclab.com]
> Sent: Wednesday, January 30, 2013 7:45 PM
> To: openstack-qa at lists.openstack.org
> Subject: Re: [openstack-qa] Return codes for OpenStack APIs
>
> I agree with this as well, and this was the consensus of the Tempest team in the past. The problem is with APIs that are undocumented about the return value, or say that there are more than one 2xx possibility but don't say under what circumstances each code would be returned. I think that in addition to requiring exact checks, we file doc bugs for the undocumented cases as we come across them.
>
>    -David
>
> On 1/30/2013 7:45 PM, Sean Dague wrote:
>> Realistically this started to come in during the 200 / 202 issues over
>> the summer.
>>
>> I think it's bad form for us to have generic 2xx testing, tempest is
>> really about testing exact behavior. My vote would be to -1 these
>> starts with tests and make the tests be explicit about what they are
>> supposed to return.
>>
>> This also lets tempest prevent accidental break of the API contract.
>>
>>      -Sean
>>
>> On 01/30/2013 06:45 PM, Sam Danes wrote:
>>> I tend to agree. The specific response code is a contract from the
>>> API that in condition X, it will return exactly Y. I would give a nod
>>> to what Daryl is saying that if the response codes were externalized
>>> and vendor configurable you could make somewhat of an argument to
>>> generalize the check, however, at that point I would think that the
>>> specific configuration that the vendor has in place should still be
>>> validated with the exact codes.
>>>
>>> We have had issues as well where a call may return say a 401 instead
>>> of a 404 which would have caused a downstream issue. A generic check
>>> for a
>>> startswith(‘4’) would have let that through.
>>>
>>> --Sam
>>>
>>> *From:*Daryl Walleck [mailto:daryl.walleck at RACKSPACE.COM]
>>> *Sent:* Wednesday, January 30, 2013 4:55 PM
>>> *To:* openstack-qa at lists.openstack.org; All Things QA.
>>> *Subject:* Re: [openstack-qa] Return codes for OpenStack APIs
>>>
>>> I'm a proponent of checking the exact code. To me, its part of the
>>> API contract. From a practical point, it has also helped our
>>> automated tests catch bugs that nearly slipped by. One case I an
>>> remember is when some various POSTs started returning a 200 code as
>>> opposed to a 202, with the end result being that the requests
>>> responded to with a 200 actually were not processed. The only reason
>>> I could think of to generalize response code checking would be if it
>>> the response codes were ever vendor configurable.
>>>
>>> Daryl
>>>
>>> *From:* David Kranz
>>> *Sent:* ‎January‎ ‎30‎, ‎2013 ‎4‎:‎08‎ ‎PM
>>> *To:* openstack-qa at lists.openstack.org
>>> <mailto:openstack-qa at lists.openstack.org>
>>> *Subject:* [openstack-qa] Return codes for OpenStack APIs
>>>
>>> There have been recent submissions to Tempest with code like:
>>>
>>> self.assertTrue(resp['status'].startswith('2'))
>>>
>>> It had been the consensus that we should be checking for actual
>>> status codes. Some projects document the return codes and others
>>> don't. This example was from a call to keystone to list services and
>>> the result is not documented but the list tenants calls says it could
>>> return 200 or 203. There should be a statement from each project
>>> about whether it considers the return code to be part of the spec.
>>> Ideally this would be uniform across projects but it is not. Users of
>>> the API really need to be able to know this. Any comments?
>>>
>>>      -David
>>>
>>> _______________________________________________
>>> openstack-qa mailing list
>>> openstack-qa at lists.openstack.org
>>> <mailto:openstack-qa at lists.openstack.org>
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-qa
>>>
>>>
>>>
>>> _______________________________________________
>>> openstack-qa mailing list
>>> openstack-qa at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-qa
>>>
>>
>>
>
>
> _______________________________________________
> openstack-qa mailing list
> openstack-qa at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-qa
> _______________________________________________
> openstack-qa mailing list
> openstack-qa at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-qa
>
> _______________________________________________
> openstack-qa mailing list
> openstack-qa at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-qa
>


-- 
Sean Dague
IBM Linux Technology Center
email: sdague at linux.vnet.ibm.com
alt-email: sldague at us.ibm.com


_______________________________________________
openstack-qa mailing list
openstack-qa at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-qa



More information about the openstack-qa mailing list