StatusCodeDescription vs. Status (ISSUE-32)

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)
  - rename "statusCodes" to possibleOutcome/possibleStatus
    (still allowing it on both ApiDocumentation *and* Operation)

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. 

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?
 2) Do we need/want to describe the exceptions that might happen?
 3) What do we lose if we don't describe it?
 4) What do we gain if we do?
 5) If we describe it, does it belong in the core vocabulary?

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 Sunday, 9 February 2014 15:29:43 UTC