On 19/05/2016 16:11, Sean Dague wrote: > On 05/19/2016 10:37 AM, Hayes, Graham wrote: >> 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 > > So, if we are going to go this direction, how would the following turn > out (just spit balling, curious on your thoughts)? > > .. rest_status_code:: status_codes.yaml > > - 400 > - 401 > - 403 > - 405 > - 409: fizbuz_lock > - 500 > > status_codes.yaml: > > - 400: > default: | > Bad Request > - 409: > default: | > Conflict > fizbuz_lock: | > The fizbuz is locked and can't be updated until unlock is performed.
++ I did not even think of doing that way, but I like it. > The reason we pushed descriptions out of the rst in the body yaml in the > first place was the moment you got to more than 60 characters and wanted > to wrap it, you lost tools assist, and indentation was manual. Yeah, that makes total sense. I can see some of the more exotic errors having a quite in-depth write up here, and that would make it much easier to write. > Especially if we want to encource full or multiple paragraphs with rst > markup. > > -Sean > I will do a rough mock out of this this evening and see what it looks like. -- Graham __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
