Re: More Thoughts on Links and Operation Subclasses

On Jan 28, 2014, at 10:08 AM, Markus Lanthaler <markus.lanthaler@gmx.net> wrote:

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

I’m not sure how this would work and it seems overly complicated. HTTP doesn’t care about a JpegFile, but rather image/jpeg, multipart/form-data, or multipart/mixed. What I was getting at with having a media type value for Operation classes is it tells the client how to send the data to the server using the Content-Type header. 

But backing up a bit, we haven’t yet defined what a Hydra client might look like and what it’s requirements are. HTML defines a limited set of media types it supports for Forms:

* application/x-www-form-urlencoded
* multipart/form-data

Other media types sent to the browser can be handles by either saving to disk, offloading to another application, or via plugins. 

Right now, Hydra isn’t explicit as to what media types it supports. At the moment, I assume that all messages are described in terms of JSON-LD. So When I read:

"expects": {
    "subClassOf": "Blob",
    "mediaType": "image/*"
  }

I feels like we’re wrapping the image data within a JSON-LD message. Is that the intent here?

I think the answer all depends on what Hydra strives to be. Is this just a description format in the same vein as Swagger, WADL, JSON Hyper Schema, etc.? Or is Hydra also trying to define a platform whereby we define a base set of client capabilities in order to clients to interact properly? This is what HTML does. AtomPub did this to a lesser extent. 

The current state of API description languages today is annoying because they rarely consider the client capabilities or programming models. They seem to assume some type of client, but really developers end up using some basic HTTP client cURL, Apache HTTP Client, etc., which don’t take into account things like caching, etags, etc. and you end up with specs like OData [1] that end up baking etags into the message body to make up for the fact that some HTTP clients don’t have a caching mechanism that deals with etags and developers are left to their own devices. 

Ryan-


[1] http://www.odata.org/documentation/odata-v3-documentation/json-verbose-format/#44_Representing_a_Named_Resource_Stream_Value


+-----------------------------------------------+
    Ryan J. McDonough
    http://damnhandy.com
    http://twitter.com/damnhandy

Received on Friday, 31 January 2014 17:11:07 UTC