[openstack-dev] [API] os-api-ref HTTP Response code formating

Qiming Teng tengqim at linux.vnet.ibm.com
Thu May 19 01:40:41 UTC 2016


<snip>

> Having some generic language for each error message if. Typing "User
> must authenticate" every time there is a 401 is tiresome, and will just
> mean typos. Ideally even generating links to an overview of what each
> code means in general would be nice. I was assuming we were going to
> write up a dedicated page about error codes.
> 
> There are times when what a 409 means pretty specific things, and I
> wonder if we want to reference it there instead of elsewhere.
> 
> I kind of wonder if:
> 
> .. rest_status_code:: 400, 401, 403, 405, 409, 500
> 
>   - 409: The fizbuz is locked and can't be updated until unlock is
> performed.
> 
> And generic messages for everything without the extra entry would work.
> 

While I do like this generalization because it will help kill typos, I'm
a little worried that we are introducing more and more REST stanza into
the docs. It would be desirable that the docs can serve both human
readers and programs that can parse it for API checking/validation.
Team, please consider this aspect when improving the doc formatting.

Regards,
  Qiming


> 	-Sean
> 
> -- 
> Sean Dague
> http://dague.net
> 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> 




More information about the OpenStack-dev mailing list