Re: StatusCodeDescription vs. Status (ISSUE-32)

> On Tuesday, February 11, 2014 9:02 AM, Thomas Hoppe wrote:
>> On 02/09/2014 04:29 PM, Markus Lanthaler wrote:
>>> OK, so summarized you propose two changes:
>>>     - move "returns" to "Status" (aka StatusCodeDescription)
>> I want to be able to describe Status (plural) comprising a `statusCode`
>> _and_ a `returns` in a central place in the API doc to be able to
>> reference these outcomes from operations thus re-using them.
>> I think yes, the move you mention would be required.
> So, you'll have for example 200/BlogPost, 201/BlogPost, and perhaps even a
> 202/BlogPost.. additionally you have a whole range of 4xx/Error. Hmm... I
> have to think a bit more about this. It would help to create concrete
> examples.

Exactly.

>
>>>     - rename "statusCodes" to possibleOutcome/possibleStatus
>>>       (still allowing it on both ApiDocumentation *and* Operation)
>> Yes.
>>
>>> I think I like the idea of combining returns with the Status
> description;
>>> even though it results in more deeply nested structures. The problem
>>> I have with this (terminology) is that overall it doesn't improve the
>>> situation much. It still feels to much like a contract instead of
>>> highlighting the fact that it is just a hint.
>> Definitely! You know that I pointed out that the status code property
>> is useless at runtime or should not be used. So my proposals are mainly
>> useful for the offline API doc use-case.
> Does that also apply to "returns" in your opinion?

Yes.

Received on Saturday, 15 February 2014 18:31:24 UTC