RE: More Thoughts on Links and Operation Subclasses

Trying to cut down the response to make it easier to follow along

On Tuesday, January 28, 2014 3:03 PM, Thomas Hoppe wrote:
> On 01/28/2014 01:45 PM, Markus Lanthaler wrote:
>> On Monday, January 27, 2014 4:19 PM, Ryan McDonough wrote:
>>> On Mon, Jan 27, 2014 at 2:51 AM, Thomas Hoppe wrote:
>>>> I have an application for this that I already posted to the list:
>>>> Think about an API where some operations underly authorization
>>>> restrictions.
>>>> Such restrictions need to be managed, for example with a role based
>>>> access control system.
>>>> What you would need to express policies such as - Owners of Role A
>>>> can carry out Operation "CreateResourceOperation" - for example are
>>>> such operations.
>>>
>>> Quite honestly, I wouldn't do that here. I would much rather make that
>>> determination before i send back the JSON-LD document to the client.
>>
>> I agree with Ryan on this but that doesn't mean that you can't define it
>> internally the way Thomas described it. In fact, I think in most cases it
>> will be done somehow like that anyway.
> 
> From the API client perspective I fully agree at runtime but there are 
> two cases where it's useful to have a concept to refer to:
> 1.) Within the 'static' API documentation... Markus sometimes mentioned 
> that he likes to Idea to have a client retrieving the
> whole API doc once and then use it as a 'site-map' for navigating 
> through it. If there are operations which are subject to AuthZ
> policies, and the client needs to make runtime decisions you would need 
> referable operations. (I know there are no such features in Hydra but I 
> think about a supplementary vocab here).

You can dynamically include/omit types (e.g. Post vs. EditablePost) and links from the representations returned by the API. The API doc would be static but the responses aren't.


> 2.) As you say, it may be used "API internally" to integrate with an 
> AuthZ solution; you need something to refer to in a policy
> and if the solution is LD based, it must be an IRI and I know of no 
> vocab which describe HTTP :)

There is some (I think abandoned) work at W3C:
  
  http://www.w3.org/TR/HTTP-in-RDF10/


> So for this use case an action vocab like parts of schema.org is the way 
> to go and therefore I also opt to
> remove the defined Operations from hydra.
 
[...]

>>>> 1.) Create an IANA Registry with some "standard" operations and
>>>> clearly defined semantics
>>>
>>> Perhaps not IANA, but have a somewhat robust set of initial operations
>>> in Hydra core would fit the bill.
>>
>> I would rather not include them into Hydra core but leverage schema.org's work:
>>     http://schema.org/docs/full.html
> 
> +1, see above. But I think schema.org should not be upraised as the only 
> normative source of operations;
> it must be clear that anyone can come up with his own operations.

Definitely!


>> If you want to define an operation which takes a binary input (e.g. an
>> image) my current thinking is that defining a special class for that would
>> allow you to do so. Something like "expects": "JpegFile". Or perhaps
>> something like "Blob" which you describe further by a media type:
>>
>>    "expects": {
>>      "subClassOf": "Blob",
>>      "mediaType": "image/*"
>>    }
> 
> ...but in this example, the `mediaType` prop is not part of the hydra 
> vocab and intuitively
> I think it makes sense to have it in there because I know of no other 
> vocab which I could use but more importantly if fits.

That example obviously assumes it exists. But before we include it we have to agree on how it has to be used. I would love to hear Ryan's thoughts on this proposal.


[...]
 
>>>>> This is also where I really start to get hanky about hydra:returns and
>>>>> hyrdra:statusCodes. Clients really need to get into the habit of
>>>>> reacting to responses and sensing content via Content-Type and
>>>>> Link headers rather than having a preconceived expectation at build
>>>>> time about what they might get back.
>>
>> Fully agreed
>>
>>>>> Perhaps abandoning the properties isn’t the right solution and
>>>>> perhaps it could be resolved through a Hydra client API. As it stands,
>>>>> these Hydra properties tee up client generators that would be a
>>>>> lot of like what tools like WADL, Swagger, etc. do now.
>>
>> Yeah of course you can misuse them. Yet I think they have value,
>> especially when you need to decide which operation to use when there are a
>> number of candidates.
> 
> I also think that they provide value for an API documentation in the 
> case when you want to explicitly specify every possible status code.
> Think about a generator which takes a hydra API doc as input and 
> generates a nice document from it.

Right, that was a use case I had in mind from the very beginning. I find it quite important as it gives you some incentives to describe your API with Hydra even if you don't expect clients to use it as such immediately but continue to use it as JSON API for some time.


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 28 January 2014 15:08:51 UTC