On 05/18/2016 02:42 PM, Hayes, Graham wrote: > I was moving Designate to the os-api-ref extension, and I spotted > something I thought we could do to improve the readability. > > Currently we have the HTTP Response Codes as a single > line on the page - I thought a table might be handy as well. > > So, I had a go at it - and put up a POC[0] > > It outputs a table with the code and the project reason for the code[1] > > Example syntax is (used to generate [1]): > > Response Codes > -------------- > > Normal > ^^^^^^ > > .. rest_response:: > > - 200: OK > - 100: Foo > - 201: Zone Created > > > > Error > ^^^^^ > > .. rest_response:: > > - 405: Method *must* be POST > - 403: Policy does not allow current user to create zone > - 401: User must authenticate > - 400: Supplied data is malformed. > - 500: Something went wrong > > Is this something worth pursuing? Should it be laid out differently?
There are a lot to like here. I think "response" is an overloaded word and I'd use rest_status_code instead for clarity. When I think about the Nova side there are a few things I think would make this better. 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. -Sean -- Sean Dague http://dague.net __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev