Re: [Specifications] CreateAction with HTTP PUT

@tpluscode: Thanks for the elaborate examples, they help (at least me) when discussing this. Is there any particular reason why `"hydra:addMember"` has an `@id`, but none of the other operations in your examples?

Also, why are there seemingly so many different ways to embed operations? Shouldn't they all go into an `operation` array?

In relation to the client understanding what an operation does, I was under the impression that `@type` in combination with `expects` was all that's needed to decipher the operation semantics? If `@type` states `schema:CreateAction` and `expects` is set to `schema:Event`, isn't it obvious that the operation creates events (within the current scope, being the `hydra:Collection`)? Do we need to complicate this further?

Sorry, but I don't fancy the `hydra:BreakLinkEffect` proposal, as it sounds way too finegrained to belong in the core vocabulary. Are side effects something we need to tackle in version 1.0 of Hydra? Isn't that something we can figure out whether is required and add on along with a plethora of other things we're guaranteed to not cover in 1.0?

Lastly, what's the difference between the properties prefixed with `hydra:` (such as `hydra:addMember`) and those who doesn't (such as `expects`)? I assumed both of these fell under the Hydra namespace and thus should preferably be the default (removing the need for the `hydra:` prefix)?

To unify the different examples given above, this is how I would want to express the three different create operations:

```javascript
{
  "@context": "/api/context.jsonld",
  "@id": "/api",
  "@type": "hydra:EntryPoint",
  "collection": [
    {
      "@id": "/api/events",
      "title": "List of events",
      "@type": "hydra:Collection",

      // Renamed "manages" to "contains" and made it a string instead of object, for simplicity.
      "contains": "schema:Event",

      // Single "operation" array to contain all operations regardless of their semantics.
      "operation": [
        {
          // All operations can be uniformly identified by their @id.
          "@id": "/api/events/new",
          "@type": ["hydra:Operation", "schema:CreateAction"],
          "title": "Create new event",
          "method": "POST",
          "expects": "schema:Event"
        }, {
          "@id": "/api/events/new",
          "@type": ["hydra:Operation", "schema:CreateAction"],
          "title": "Create new event",
          "method": "PUT",
          "expects": "schema:Event",

          // If the target is a string, it's implicitly of @type: '@id'. I have no idea if this is possible with JSON-LD, but this flexibility would be neat and make the format simpler.
          "target": "/api/events/06c31878411c45ffa0996c45a3a58eb1",
        }, {
          "@id": "/api/events/new",
          "@type": ["hydra:Operation", "schema:CreateAction"],
          "title": "Create new event",
          "method": "PUT",
          "expects": "schema:Event",

          // If the target is an object, it will most likely always be a 'hydra:IriTemplate', possibly making the @type property automatically inferred and obsolete (I hope)?
          "target": {
              "@type": "hydra:IriTemplate",
              "template": "/api/events/{?uuid}",

              // No 'hydra:' prefix if possible.
              "mapping": {
                "variable": "uuid",
                "property": "id:uuid",
                "required": true
              }
          },
        }
      ]
    }
  ]
}
```

With this uniformity, it's pretty easy to write a client, since all operations can be handled the same way. You just need to see if there's a `target` property, and if it is, use it as the URI (or as a template to build the URI) to perform the operation against.

Please don't hesitate to out all the errors I've made above. 😃 

-- 
GitHub Notification of comment by asbjornu
Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/141#issuecomment-337034493 using your GitHub account

Received on Monday, 16 October 2017 20:41:24 UTC