New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
awwright opened this Issue Oct 8, 2016 · 5 comments

Comments

Projects
None yet
3 participants
@awwright
Member

awwright commented Oct 8, 2016

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

This comment has been minimized.

Show comment
Hide comment
@jdesrosiers

jdesrosiers Oct 15, 2016

Collaborator

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.

Collaborator

jdesrosiers commented Oct 15, 2016

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

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Oct 15, 2016

Member

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.

Member

handrews commented Oct 15, 2016

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

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Oct 18, 2016

Member

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

Member

handrews commented Oct 18, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Sep 3, 2017

Member

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.

Member

handrews commented Sep 3, 2017

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

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Sep 14, 2017

Member

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.

Member

handrews commented Sep 14, 2017

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.

@handrews handrews closed this Sep 14, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment