Open Stack

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


> 	-Sean
>