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.


> >    - 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?


> I think "possibleStatus" is pretty vague already but on the other hand
> I think this is something that must be stressed in the prose part of
> the spec because it is of fundamental significance and requires an
> understanding of the REST architecture model.
> There will be many people coming from a contract first background and I
> think you could even name the properties like
> "statusCodeUseThisAsHintThereMightBeOthers"
> and they would still take it as contract because humans are creatures
> of habit.

Fair enough. There's only so much we can do.



--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 11 February 2014 19:00:12 UTC