Expressing actions (#154) within ApiDocumentation

[tpluscode]

On today's call we discussed that the premise of PR #154 is to allow, as the title states, performing requests on a different target. That is, as opposed to hydra:Operation which always assumes that the target will be the object of a ?s hydra:operation ?o triple.

Taking advantage of supportedProperty and supportedOperation combined should make it also possible.

Let's have a car resource, linked to a steering wheel:

{
  "@type": [ "ex:Car" ],
  "@id": "/the/car",
  "ex:steeringWheel": {
    "@id": "/the/wheel"
  }
}

We can currently define the ApiDocumentation so that any occurrence of ex:steeringWheel implies that its subject will support given operations:

{
  "supportedClass": {
    "@id": "ex:Car",
    "supportedProperty": {
      "@id": "ex:steeringWheel",
      "supportedOperation": [ {
        "@type": "ex:TurnLeftOperation"
      }, {
        "@type": "ex:TurnRightOperation"
      } ]
    }
  }
}

This way any subject of ?car ex:steeringWheel ?subject will be a assumed a valid for the turn operations, regardless of it's precise class. I think it should be also allowed to have an IriTemplate in place of /the/wheel

{
  "@type": [ "ex:Car" ],
  "@id": "/the/car",
  "ex:steeringWheel": {
    "@type": "IriTemplate"
  }
}

@lanthaler please confirm I'm not inventing my own Hydra here. @elf-pavlik how would similar be expressed with ApiDocumentation and the actions being discussed in #154

[lanthaler]

Just to make sure we are on the same page. The target of the ex:TurnLeftOperation and ex:TurnRightOperation would be /the/wheel, not /the/car.

The same is supported for IRI Templates. The property should be typed as hydra:TemplatedLink in that case.

Why did you split this off into a separate issue instead of discussing it in the context of #154?

[alien-mcl]

We agreed that #154 is more about actions in general, this issue is more related to some technical solutions of achieving API documentation with both current hydra spec and hypothetical modifications (like the actions mentioned)

[elf-pavlik]

While I agree that we can consider this issue independently from PR #154 , let's still stick to UC5.1 and hydra:memberTemplate. Would we have something like

{
  "supportedClass": {
    "@id": "hydra:Collection",
    "supportedProperty": {
      "@id": "hydra:memberTemplate",
      "supportedOperation": [ {
        "@type": "schema:CreateAction"
      } ]
    }
  }
}

?

But that would mean that any hydra:Collection in that API supports schema:CreateAction, what if in our case only collection that manages resource of type schema:Event does support this operation and other collections do not? It seems that hydra:ApiDocumentation does not play well with hydra:manages block all together.