Re: StatusCodeDescription vs. Status (ISSUE-32)

On 02/09/2014 04:29 PM, Markus Lanthaler wrote:
> Changing the subject as this has really more to do with ISSUE-32 than
> ISSUE-25,  ISSUE-27 & ISSUE-28 (singularization).
>
> On Friday, February 07, 2014 12:22 AM, Thomas Hoppe wrote:
>> On 02/06/2014 05:46 PM, Markus Lanthaler wrote:
> [...]
>>> Maybe it helps if we look separately at statusCodes used on
>>> ApiDocumentation from statusCodes used on Operation. On an
>>> operation, I think it's reasonable clear. The enumeration of
>>> statuses describes possible outcomes of invoking that specific
>>> operation. On the ApiDocumentation, on the other hand, it is not
>>> so obvious; especially not if we just call this thing "Status" and
>>> "possibleStatus".
>>>
>>> I think what we try to describe on the API level is what kind of
>>> potential errors/exceptions etc. a client should be able to
>>> handle. Now it depends on us how we model this. I think just using
>>> the obvious approach to reuse the same thing that seems to work on
>>> operations isn't really an option here (at least not with the
>>> proposed property "possibleStatus"). A possible approach would be
>>> to describe error scenarios that result in a specific status.. if
>>> you run over quota, you will get back this status. That could
>>> easily turn in something quite complicated unless we restrict
>>> ourselves (for the time being) to describe the error condition,
>>> i.e., the circumstances that lead to the error/status only in
>>> natural language. What I have in mind is something like this:
>>>
>>>     ApiDocumentation
>>>       - cornercases:
>>>           - name: Quota Limit Hit
>>>             desc: If you send more than 100 req/s you'll
>>>                   get an error
>>>             status:
>>>               - statusCode: 429
>>>                 name: ?? duplicated ??
>>>                 desc: ?? duplicated ??
>>>
>>> As you already see from the sketch, it's not fully thought
>>> through yet. I'll have to think more deeply about this.
>> I have a different idea.
>>
>> I think we agree that we have the following entities in APIs:
>> - Staus (good, bad)
>> - Operations
>> - Resources
>>
>> Let's remind what most today's APIs do with them:
>> There are a number of resources which _almost_ all share the same
>> operations (at least if the API mainly deals with low level CRUD
>> operations
>> which is the standard today). Some operations might have
>> additional or different outcomes.
>>
>> In an OO model you would model this with a base class containing
>> the common parts hand handle the variance with inheritance.
>> If I also pull the Status Instances in a separate enumeration,
>> this might look like this:
>>
>> BaseClass {
>>       "supportedOperations": [
>>           "@type": "CreateResourceOperation",
>>           "title": "Creates a new comment",
>>           "method": "POST",
>>           "possibleOutcome": [
>>               "good", "bad"
>>            ],
>>            ...
>>       ]
>> }
>>
>> SpecialClass {
>>       "parentClass": "BaseClass",
>>       "supportedOperations": [
>>           "@type": "RetrievePayedContentOperation",
>>           "title": "Creates a new comment",
>>           "method": "GET",
>>           "possibleOutcome": [
>>               "notpayed"
>>            ]
>>        ]
>> }
>>
>> PossibleStatus [
>>
>>           {
>> 	   "@id": "good",
>> 	   "statusCode": 201,
>>              "returns": "http://www.w3.org/ns/hydra/core#Resource
>> <http://www.w3.org/ns/hydra/core#Error>
>> <http://www.w3.org/ns/hydra/core#Error>",
>>              "title": "Successfully created",
>>              "description": "The resource has been created successfully"
>>            },
>>            {
>> 	   "@id": "bad",
>> 	   "statusCode": 400,
>>              "returns": "http://www.w3.org/ns/hydra/core#Error",
>>              "title": "Bad Request",
>>              "description": "You've sent invalid JSON"
>>            },
>>            {
>> 	   "@id": "notpayed",
>> 	   "statusCode": 402,
>>              "returns": "http://www.w3.org/ns/hydra/core#Error",
>>              "title": "Payment Required",
>>              "description": "Payment is required to conduct this
>> operation"
>>            }
>> ]
>>
>> Basically I propose that we should not just enumerate the status
>> but we should have a way to relate them to supported operations of a
>> class.
>> This should allow for a terse but concise description.
>> The inheritance stuff is optional and just to save code;
>> it must also be possible to describe the outcome for each operation
>> separately (inline).
>> I hope you get the Idea, just hacked this together.
> 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.

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


>
> IMO, there are a couple of fundamental questions we have to answer before we
> can decide on the proper naming:
>
>   1) Do we need/want to describe what an operation returns?
Maybe in "hydra-doc" :)

>   2) Do we need/want to describe the exceptions that might happen?
If we do 1.), we should do 2.)

>   3) What do we lose if we don't describe it?
Nothing at runtime

>   4) What do we gain if we do?

Offline Api-Docs

>   5) If we describe it, does it belong in the core vocabulary?
Maybe not.

>
> I think we want (but not necessarily need) to describe 1) and 2). From a
> programming perspective I think we wouldn't lose that much (3) as most of
> these hints are not machine-readable. "returns" on an operation *might* be
> valuable (4) also from a programming POV at it might help you to choose the
> right operation if there are a couple of options. The fact that I'm unable
> to come up with a good example, however, indicates that it might be a
> fallacy. It would help programmers reading a service's documentation so, at
> least the status code stuff, doesn't really belong in the core vocabulary
> (5) but might be better moved to a "documentation vocabulary".
>
> I'm still a bit on the fence about "returns". Has someone other use
> cases/examples of how the information it provides might be used
> programmatically?
>
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>

Received on Tuesday, 11 February 2014 08:02:07 UTC