edit and edit-media are covered by ATOMpub, but rel is not an attribute with a fixed range of values. Which means that the information a developer needs isn't there with the link, instead one has to go off and for each link relation try and find the original first citation, hopefully in a spec, which defines for that particular link relation the method to use. Then the developer has to hope that the API implementor also knew about that spec and did the right thing.
My criticism is that link relations fails to describe the valid verbs for a link. And there is no appropriate place to put it. We're being told about a link, but now how to interact with it.
We're given half of the story: this link relates to this item in this way (rel attribute), and you can expect it to hold this content type (type attribute) and it's over here (href attribute).
But the missing part of that story is "and to make a call to this particular end point you need to use one of these methods: HEAD, or GET".
We could use OPTIONS of course, that's the point of it. But pragmatism kicks in and when I've in the past gone done a purity route and had people do things like this... developers start to kick back. They end up with a very chatty API and lots more code than they need to perform a simple action. The audience of an API remains the developer and keeping to a purity line just causes most developers pain (not all devs, some prefer purity).
Going back to the example in the linked cookbook, they had a bank and a deposit resource. You can reasonably expect that the API permits a new deposit, permits fetching information about an existing deposit, but in the case of a bank account won't allow you to edit or delete a deposit once it's been made... you need to make a new deposit to fix that.
So reasonably links should have been returned that pretty much said:
DELETE wasn't allowed for either, and PUT and POST depended on the end point.
I shouldn't do that though, as 'methods' is a gibberish attribute I just made up and no client will know what to do with that.
I should use OPTIONS, but then if you follow that through why include a 'type' attribute as you could've got that info from OPTIONS? (The entity-body of the OPTIONS response could give you the type information and even describe the schema of the resource).
I guess where I'm at is that once you start printing links according to what the user (not client) of the API can or cannot do, you're effectively echoing permissions through the use of links. And that permissions go beyond which resources can be touched, and into what actions you can perform on those resources. Meaning that to express this properly we start needing to be able to communicate which verbs are good for this user, for a given resource. Requiring a second HTTP request for everything to check these permissions seems a bit crazy in practise (very chatty APIs) though great in theory (conformance to every spec there is).
And what we're doing at the moment is opaque as the information on those interactions that the user can perform is held in different places, in the link, in OPTIONS, and additionally in specs. To a developer implementing against this, they're not given an easy way to just answer the question "What can I do right now?"... we give them half the information they need and leave it as a job for the developer to figure out the rest.
BTW: Respect for your book, thanks for replying as I'd love to hear your views on the above.
> BTW: Respect for your book, thanks for replying as I'd love to hear your views on the above.
<3. Trying to get more good stuff out there...
> Then the developer has to hope that the API implementor also knew about that spec and did the right thing.
This is why relations that aren't specified in your media type or in the IANA list are supposed to be URIs. If they're not, they're breaking the Web Linking spec.
> But the missing part of that story is "and to make a call to this particular end point you need to use one of these methods: HEAD, or GET".
There is no reason that text cannot be in every link relation. It's just not. When defining your own, absolutely add that in.
> And that permissions go beyond which resources can be touched, and into what actions you can perform on those resources.
This is certainly a good insight.
> Requiring a second HTTP request for everything to check these permissions seems a bit crazy in practise
Link relations can absolutely say this. See ATOMpub as one example, it's `edit` relation specifies that you should use PUT.