Hyper-schema: "Allow"/acceptable methods link attribute

[awwright]

The current "method" keyword doesn't quite have the semantics we're looking for.

Change the definition or replace with a keyword that lists allowable HTTP methods, instead (as a hint).

[jdesrosiers]

I think this is a good idea, but there are some wrinkles that would have to be discussed.

GET, PUT, and DELETE have very specific semantics, so there is no reason we need to do anything more than express that those methods are available.

The caveat with PUT is that the Hyper-Schema MUST include JSON Schema validation constraints to describe the resource. If it doesn't, there is nothing to tell a client the structure the server expects with a PUT operation. This wouldn't work if you just wanted to send the just the LDO part of the Hyper-Schema instead of the full thing. I think I'm ok with this, but it is a little awkward. I'll have to think about it some more.

Then there is POST. Any time you are doing a POST, you need to describe what input you expect using a JSON Schema. What would the LDO look like in this case. Here's one option.

{
  "href": "/foo",
  "allow": ["GET", "PUT", "DELETE", "POST"],
  "schema": { ... }
}

That would be awkward because "schema" only applies to POST, but that isn't clear. Another option would be

{
  "href": "/foo",
  "allow": [
    "GET",
    "PUT",
    "DELETE",
    ["POST", { ... schema ... }]
  ]
}

This makes it clear that the schema applies only to POST, but there might be a better way.

Then there is the link building functionality that was previously handled by the presence of GET and a "schema". How would you describe link building? That might be a completely different issue, but it will have to fit in here somewhere at some point.

[handrews]

Then there is the link building functionality that was previously handled by the presence of GET and a "schema". How would you describe link building?

If you mean encoding input into the URI for the link, it should be done as proposed in issue #52 (extended templating) which allows for more flexible URI encoding (not just the query string). There should be a mechanism analogous to that proposal's vars for mapping instance data into request bodies- we didn't have such a thing in the Riverbed service definitions and it turned out to be a major oversight.

[handrews]

@awwright Is allow intended as a schema keyword or an LDO keyword? It makes sense as a schema keyword in the same way as media and readOnly. But you can't get the schema of the resource on the far end of a link without fetching the resource and checking it's runtime profile, so that seems to be of limited use for a keyword intended to let you reason about a resource without dereferencing it.

If it's an LDO keyword, does it only apply to self? If not, schema authors would need to duplicate for all links that point to the same resource, which seems bad. Then again schema, targetSchema and mediaType have exactly the same problem. If resources A, B, and C all have a link/form with the same rel to X, then the LDO for that link has to be declared three times. Some members of the LDO can be put in a common place and $ref'd in, but not all.

[handrews]

If PR #383 gets accepted for draft-07, I plan to close this as it is a solution to the general problem.

There has been some suggestion of also having an "allow" property as a shortcut even alongside of "targetHints", but I would like to give "targetHints" a chance to gather usage feedback on its own.

If it turns out not to be sufficient, we should open a new issue based on the draft-07 feedback rathe than leaving this sitting open confusing anyone who stumbles across it.

[handrews]

As noted, in the previous comment, let's see how "targetHints" works for solving this problem. If, after feedback from actual implementations, it's clear that we need a shortcut for protocol methods, we can file a new issue based on that specific feedback.