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)?
The important questions I see here are :
Consider the following:
Shouldn't those resource relationships for create, update, etc all be rel="self"? Wouldn't it make more sense to write :
In answer to your question, I would say that the 'close' relation and url are not appropriate except as a GET to a resource returning a representation containing a form which could be used to issue an unsafe request to some other resource such as the issue itself or a subordinate resource such as status. So as a shortcut, status makes more sense:
Which might elicit a client request such as: