Open Stack

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