- From: Thomas Hoppe <thomas.hoppe@n-fuse.de>
- Date: Fri, 07 Feb 2014 00:21:31 +0100
- To: public-hydra@w3.org
On 02/06/2014 05:46 PM, Markus Lanthaler wrote:
> Let me try to wrap this thread up in a single mail:
>
> On Wednesday, February 05, 2014 6:20 PM, Ruben Verborgh wrote:
>> The puil request that singularizes the discussed properties is
>> available at
>> https://github.com/HydraCG/Specifications/pull/34
> Thanks a lot for taking a stab at this Ruben. Much appreciated. It LGTM but
> as you say
>
>> [...] the statusCodes issue needs fixing before it can be
>> singularized:
>> https://github.com/HydraCG/Specifications/issues/27
> On Thursday, February 06, 2014 2:14 PM, Ruben Verborgh wrote:
>> To decide on this, let's see what each property is supposed to mean.
>>
>> The current `statusCode` associates a `StatusCodeDescription` with an
>> actual HTTP status code. I think that it doesn't make much sense to
>> express that "a description of a status code has a status code". You're
>> either describing a status code, which would then be
>> `http://example.org/404 a :StatusCode.` and attaching properties to it;
>> or you're describing a status. Looking at the example from the spec:
>>
>> {
>> "@context": "http://www.w3.org/ns/hydra/context.jsonld",
>> "@type": "StatusCodeDescription",
>> "statusCode": 429,
>> "title": "Too Many Requests",
>> "description": "A maximum of 500 requests per hour and user is
>> allowed."
>> }
>>
>> we can see that we are describing a `hydra:Status`, _not_ a status
>> code. We are saying that there is a status where the user has hit the
>> 500 requests per hour limit, and that this will result in a 429
>> response.
> That's a very interesting and compelling way to look at it.
+1
>
>
>> Hence, I think the correct way would be:
>>
>> {
>> "@context": "http://www.w3.org/ns/hydra/context.jsonld",
>> "@type": "Status",
>> "statusCode": 429,
>> "title": "Too Many Requests",
>> "description": "A maximum of 500 requests per hour and user is
>> allowed."
>> }
>>
>> So the message "you hit the limit" is a status, not a code. The
>> property `statusCode` can be reused in this scenario.
> Right. I think it makes it much clearer why Error is a subclass, i.e., a
> specialization of StatusCodeDescription (aka Status).
>
>
>> The other issue is then how to associate such a status with a resource
>> (= the current `statusCodes`). I am in favour of using `possibleStatus`
>> for this, as this conveys the meaning of what the thing does.
>>
>> But then I'm unsure about the domain of this property. What can be in
>> this possible status? A single resource? The whole API (= all resources
>> in this API)?
> 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.
>
>
>
> The other thing we need to discuss in this context is whether we want to
> have properties that differ only in their capitalization, as, e.g.,
> Schema.org (ISSUE-28).
>
> If we merge Ruben's pull request, there are a couple of properties that
> differ only in their capitalization from their corresponding types:
>
> hydra:apiDocumentation -> hydra:ApiDocumentation
> hydra:operation -> hydra:Operation
> hydra:supportedProperty -> hydra:SupportedProperty
>
>
> Ruben thinks
>
>> that's totally fine actually.
>> Introducing artificial differences might make this more difficult.
> and, if desired, proposed the following alternatives on GitHub:
>
> hydra:documentedBy -> hydra:ApiDocumentation
> hydra:supportsOperation -> hydra:Operation
> hydra:supportsProperty -> hydra:SupportedProperty
>
> Gregg proposed
>
> hydra:hasApiDocumentation -> hydra:ApiDocumentation
> hydra:hasOperation -> hydra:Operation
> hydra:hasSupportedProperty -> hydra:SupportedProperty
>
> Schema.org typically adds a "Type" at the end. They have, e.g., an
> "eventStatus" property which points to an "EventStatusType". I don't
> particularly like that because it looks quite ugly, especially if you use
> Turtle's "a":
>
> _:something a EventStatusType .
> <docu> a ApiDocumentationType .
>
> It is, however not an even status *type* or API documentation *type* but an
> instance thereof.
>
> I would like to hear a couple of more opinions but I'm leaning towards
> keeping the properties and the types the same (apart from their
> capitalization). Is there someone who can't live with that?
I like Ruben's variant most with just different capitalization most.
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
Received on Thursday, 6 February 2014 23:22:00 UTC