Open Stack

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.

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.

Especially if we want to encource full or multiple paragraphs with rst
markup.

	-Sean

-- 
Sean Dague
http://dague.net