RE: More Thoughts on Links and Operation Subclasses

On Friday, January 31, 2014 6:11 PM, Ryan J. McDonough wrote:
> On Jan 28, 2014, at 10:08 AM, Markus Lanthaler 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.

JpegFile would be a class corresponding to image/jpeg in that case. The blob
example is basically the same but avoids the need to define a class for each
possible media type.


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

Yeah, I got that.


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

At the moment, Hydra is limited to RDF-based media types such as JSON-LD or
Turtle.

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

No, the intent was to create a special class which instructs the client to
send a message using (one of) the specified media type(s); in this case an
image.


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

I think it will become necessary to define classes of clients and their
capabilities sooner or later. This should, IMO, be mainly driven by
implementations.


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

IMO, the problem is that every API is a snowflake these days. You can't
implement a generic client and thus you very rarely have the incentives to
invest in a high-quality client. cURL etc. are generic, off-the-shelf tools
that help you to get the job done. As soon as we have something interesting
enough, I hope there will be enough incentives to build a sophisticated,
generic client for it. I hope we'll achieve that with Hydra.


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


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 3 February 2014 20:32:45 UTC