[openstack-dev] Defining API Success in OpenStack APIs (specifically Swift)

Mark McLoughlin markmc at redhat.com
Thu Jun 20 12:28:34 UTC 2013


On Thu, 2013-06-20 at 07:21 -0400, Sean Dague wrote:
> The following patch review came into Tempest yesterday to stop checking 
> for specific 20x codes on a number of Swift API - 
> https://review.openstack.org/#/c/33689/
> 
> The official documentation for these APIs says the following - 
> http://docs.openstack.org/api/openstack-object-storage/1.0/content/retrieve-account-metadata.html
> 
> "The HTTP return code will be 2xx (between 200 and 299, inclusive) if 
> the request succeeds"
> 
> This seems kind of broken to me that that's the contract provided. I've 
> got a -1 on the patch right now, but I think this is worth raising for 
> broader discussion. It seems to go somewhat contrary to 
> https://wiki.openstack.org/wiki/APIChangeGuidelines and to the spirit of 
> having stable, well defined interfaces.
> 
> So I guess I open up the question of is it ok for OpenStack core 
> projects to not commit to success codes for API calls? If so, we'll let 
> the test change into Tempest. If not, we probably need to call that out 
> on API standards.

In one way, it's actually perfectly valid. A perfectly written client
should perhaps have generic logic around handling different status
codes. For example, if it requires that an action be completed, it
should know to poll for completion if it gets a 202 Accepted.

If clients were written with that kind of logic, then all would be well
with our "return code between 200 and 299" contract but the reality is
that people will code their clients - no matter what the docs say -to
the specific return codes we send back right now and they'll probably
break if we change the status codes.

So, yeah - pragmatically speaking, I think we need to commit to not
changing success return codes for existing clients. Maybe new clients
could opt-in to the new behaviour somehow if we do need to change.

Cheers,
Mark.




More information about the OpenStack-dev mailing list