Open Stack

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