People have been talking about including hypermedia with REST Resources, but
there are very few public examples that implement all of it. One common
technique is to add *_url
attributes:
{ "id": 1
, "self_url": "/issues/1"
, "comments_url": "/issues/1/comments"
}
This only gives you room to put a URL. Because of this, I've been leaning towards HAL:
{ "id": 1
, "_links":
{ "self": {"href": "/issues/1"}
, "comments": {"href": "/issues/1/comments"}
, "close": {"href": "/issues/1/close", "method": "post"}
}
}
Should hypermedia tell you when you have permissions to access those resources?
// admin permissions
{ "id": 1
, "_links":
{ "self": {"href": "/issues/1", "method": "get,patch,delete"}
, "close": {"href": "/issues/1/close", "method": "post"}
}
}
// read-only permissions, no access to close/update issues
{ "id": 1
, "_links":
{ "self": {"href": "/issues/1", "method": "get"}
}
}
The HAL spec doesn't mention method
properties at all. But, I think letting
a client know the difference between an Issue I can edit or close is very
useful. Is it any better if I have a separate relation for each action?
{ "id": 1
, "_links":
{ "self": {"href": "/issues/1", "method": "get"}
"edit": {"href": "/issues/1", "method": "patch" }
"delete": {"href": "/issues/1", "method": "delete" }
, "close": {"href": "/issues/1/close", "method": "post"}
}
}
Finally, is the "close" relation even appropriate? Or should I assume clients know they can close Issues by setting "state" to "closed" (which is how the GitHub Issues API works)?
I like where you're going with this. You're definitely on the right track.
To reiterate @steveklabnik, absolutely.
I think where things are starting to get awkward is outbound links (LO), templated queries (LT), non-idempotent update (LN), and idempotent updates (LI) all use the same
_links
control. HTML gets away with it by having 2 separate controls:A
for LO links,FORM
for LT and LN links, and it doesn't have LI links. Collection+JSON separates these actions into links, queries, and templates.To write this in HTML, I think you'd know exactly how to represent these actions. If you had access to edit an Issue, you'd find a form on the page containing a few inputs to fill in or change. HTML defines how a client should submit this back to the server.
Likewise, if you has permissions to close an Issue you'd find a button on the page which is simply another form with a hidden input.
If the permissions to edit and close are one in the same, there's no reason why these two forms can't be combined by adding a checkbox to close or re-open the Issue.
This is oversimplified but it helps me to step back and think of this in terms of a media type with which I'm intimately familiar.