On 18/05/2016 20:12, Sean Dague wrote: > 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.
Yeah - that's a much better term > 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. Yeah - that is a good idea. Should the generic messages live in os-api-ref tree, or project tree? I would lean towards the projects personally, and based on that something like: .. rest_status_code:: status_codes.yaml - 400 - 401 - 403 - 405 - 409: The fizbuz is locked and can't be updated until unlock is performed. - 500 > -Sean > __________________________________________________________________________ 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