search

kevinswiber / siren

Structured Interface for Representing Entities, super-rad hypermedia
MIT License
1.3k stars 71 forks source link

Add rel for actions #56

Open dominicbarnes opened 9 years ago

dominicbarnes commented 9 years ago

While looking through the list of link relations, I discovered things like create-form and edit-form, which I thought would make sense in the context of an action.

Would adding rel make sense for actions? Since actions have an href, I think this technically makes it a link, but I'm still learning the vernacular of hypermedia.

kevinswiber commented 9 years ago

@dominicbarnes Sorry for the delay. I've used create-form and edit-form link relations in the past, but I've used them as that--links. The response returned from following the link includes an action for creating or editing. The benefit here is that if the action itself is lengthy, it doesn't have to be included in the entity's GET response for those who just want to view.

A relation on an action would change from "why do you want to follow this link?" to "why do you want to execute this request?" For that information, I tie it to documentation with the action name. That said, there's no reason an action name couldn't be a URI. It just doesn't have to be, per the spec.

dominicbarnes commented 9 years ago

Ok, I can understand that reasoning. I guess my main question is why actions are treated differently than links in this regard?

Rather, why is the discoverability of actions different than that of links? By not having any sort of URL tied to the name of an action, the only way to discover more about that action is to read external documentation. This difference doesn't fully align with siren's goal of making an API discoverable. Thus, using a URL with the name field seems like a reasonable workaround in the short-term.

However, I would like to formally propose a long-term solution by using rel instead. This would make actions consistent with links, thereby simplifying siren itself and making discoverability a first-class feature of actions as well. For backwards-compatibility, the name can remain in use, but my ultimate aim in this proposal is to replace name with rel in the long run.

shaunparsloe commented 8 years ago

I'm in agreement with @dominicbarnes in this. The fact that a link has a rel attribute and an action has a name attribute is confusing - especially when both of them are used in the same way as a key to discover the href.

pke commented 4 years ago

Just implementing a new REST API loosely based on SIREN and rel it will be. I think it will only have actions and no links, since links are just GET actions in the end, or aren't they?