Actions in Schema.org / Hydra

Hi all,

I've finally had a chance to read the Actions in Schema.org proposal
(2013-05-11 draft) and would like to give some feedback. I've seen the first
draft last year but I didn't realize that you are working on something quite
similar to what I'm trying to achieve. I've been working for quite some time
now on a vocabulary to describe Web APIs. It's called Hydra and, if you are
interested, you can find more information on my homepage:

  http://www.markus-lanthaler.com/hydra/

It is great to see that we made quite similar design decisions. For example,
I use "Operation" types whereas you use "Action" types to convey the
semantics. While Hydra is just concerned about describing service
interfaces, your approach tries to address more use cases, e.g., activity
logs. This of course lead to some (I think minor) differences.

Before I'm going to show how Hydra differs from your proposal, I have a
couple of questions regarding some design decisions you made.

Currently you define four ActionHandlers, namely ApplicationHandler,
InlineHandler, WebHandler, and WebFormHandler. I'm not sure I understand the
use case or rationale behind the ApplicationHandler. Why do you need to
describe the application when you use a URL such as
"netflix://play?movie=skyfall" as the target? This alone would allow the OS
to launch the right application, right? How is a client supposed to use that
information? For example, what should it do if the application is not
installed? Should it ask the user for permission to install it?

I find the SoftwareApplication.handles + HandlerTarget much more compelling
because I fear that ApplicationHandler will lead to the same NASCAR user
interfaces that OpenID suffered from. The HandlerTarget approach in contrast
enables a user agent to show only options relevant to the user.

Do I understand it correctly that a WebHandler is an InlineHandler with the
method fixed to GET? So, basically just a link? Wouldn't it in that case
make more sense to create properties that can be used to express such a link
as a simple value instead of doing the whole Action/Handler dance?

I'm also not sure I understand why in WebFormHandler you separate the URL
from the formId. Wouldn't it be possible use a URL which references the form
using a fragment identifier? Something like
http://example.com/form.html#formId?

What happens if an action has both a "url" property and an associated
handler? Is that the same as specifying multiple handlers? How does a client
know which handler to use if there are multiple?

I have to say that I'm a bit concerned about the notion of a "handler" in
general as it encourages RPC-style interfaces in contrast to a RESTful
architecture. With Hydra I took a different approach to avoid that. Hydra
describes the operations a resource supports. So, e.g., to describe that a
resource can be deleted by an HTTP DELETE request you would do the following
in Hydra:

{
  "@context": "http://purl.org/hydra/core",
  "@id": "/a-resource",
  "desc": "This resource can be deleted with an HTTP DELETE request"
  "operations": [
    {
      "@type": "DeleteResourceOperation",
      "method": "DELETE"
    }
  ]
}

You would express that as follows

{
  "@context": "http://schema.org",
  "@id": "/a-resource",
  "desc": "This resource can be deleted with an HTTP DELETE request"
  "action": [
    {
      "@type": "DeleteResourceOperation",
      "handler": {
        "@type": "InlineHandler",
        "method": "DELETE",
        "url": "/a-resource"
      }
    }
  ]
}

Right?

I think this already nicely illustrates the main difference between our
approaches. You separate Actions and ActionHandlers whereas Hydra describes
resources and the Operations they support. As I said above, it could be
compared to RPC-style vs. REST-style. The advantage I see in Hydra's
approach is that it allows you to bind operations to classes or properties.
So you can, e.g., express that all DeleteableResources support a
DeleteResourceOperation. This allows you to describe complete Web APIs in a
declarative way without having to describe it for every single resource. On
my homepage you also find a simple demo leveraging that:

  http://www.markus-lanthaler.com/hydra/console/

The other main difference I see is that Hydra uses classes to describe the
required/optional properties an operation expects whereas you define that
directly on a the ActionHandler. This probably stems from the fact that
Hydra is based on the assumption that a client can retrieve that information
at runtime if necessary by dereferencing the class. A class then defines the
required/optional properties just as you do, i.e., it does not rely on
rdf:domain to figure that out.

I would appreciate your opinion on Hydra's design. Maybe we'll even be able
to combine the best ideas of both in a even stronger design. I would be more
than happy to collaborate to make this happen.


Cheers,
Markus



--
Markus Lanthaler
@markuslanthaler

Received on Saturday, 8 June 2013 17:11:55 UTC