On 19/05/2016 14:09, Anne Gentle wrote: > > > On Wed, May 18, 2016 at 1:42 PM, Hayes, Graham <graham.ha...@hpe.com > <mailto:graham.ha...@hpe.com>> wrote: > > I was moving Designate to the os-api-ref extension, and I spotted > something I thought we could do to improve the readability. > > > Thank you! > > > > 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? > > > Definitely worth pursuing. > > How will teams get to more definitively describe the responses? For > example, these descriptions for Compute errors: > > The operation is not allowed because the corresponding > server is in a build state. > > or > > The operation is not allowed because the corresponding > server is being re-sized or backed up.
Sure - they would do something like this: .. rest_response:: - 409: The operation is not allowed because the corresponding server is in a build state. Sean suggested having generic messages, and then allowing them to be overridden if the situation calls for it, which I am also looking at. > If those descriptions are embedded in the Sphinx extension, I think > we'll need to enable more detailed descriptions, and simply want to > understand how. When I looked at the code, that was my question in the > review - help me understand the mechanism better. Yeah, definitely. Currently the only info embedded in the extension is the RFC title ( so 200 has the the string "OK", 201 has "Created" embedded). I think it should really be a per project thing, with maybe an example starter YAML file in the docs for os-api-ref? -- Graham > Thanks a bunch for doing this! > Anne > > > > > Thanks, > > -- Graham > > 0 - https://review.openstack.org/#/c/318281/1 > 1 - http://i.imgur.com/onsRFtI.png > > _______________________________________________ > OpenStack-docs mailing list > openstack-d...@lists.openstack.org > <mailto:openstack-d...@lists.openstack.org> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs > > > > > -- > Anne Gentle > www.justwriteclick.com <http://www.justwriteclick.com> __________________________________________________________________________ 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