URIs should be the go-to identifier for every API request, including linking. Never IDs. This provides polymorphism for free, and frees the server to change internal ID representations if it ever needs to.

<aside> 🤔 But what about Veneto’s commitment to strong typing? Our approach to coupling the client and the server only applies to the data schema - resource identifiers must remain decoupled

</aside>

Background

There was an HTTP LINK method draft created by Tim Berners-Lee that appears to have been abandoned many years ago. Its use case, however, is still valid, and I’ve used it before.

Linking is taking an existing resource (the target) and applying it to the relation of another existing resource (the destination).

TBL’s specification explains that for the LINK method “no storage is requested for the destination object”. While the implementation details should be hidden from the client, the general principle is nice to establish.

The problem there is that the implementation is hideous - it uses the Link header with its weird syntax, and the proposal acknowledges that nothing is stopping the client from sending multiple links, in which case, if the server only needs one, it just has to choose the latest one. This undefined behavior is pretty brutal.

Proposal

I’d like an easy way to expose endpoints for this, in a standardized way that makes sense for most applications

One way is to have a wrapper resource class that allows PUT, but I want to make sure there’s an easy way in re Custom / dynamic link serialization to not have to handle the wrapper client side for dynamic links

❓

• What should the argument be? I like URIs, but unfortunately we lack an easy Standard bidirectional URI mapping solution for most server implementations. Maybe that can be our next scope creep
  • We could use the text/uri-list mime type, but that just introduces the bidirectional mapping concerns discussed above.
  • One key benefit to that is sharing the same POST endpoint - this is semantically fine as POST only requires that the server “process” the representation. Not necessarily the case for PUT
  • But, it’s not extensible, in case there are any other parameters the user wants to introduce
  • It can also accept multiple, but cannot be limited to a singular one. which is annoying

Accepting a medium union between URI and Key is also an option but just more complicated…

I do think I’ll go with the URI. we should just introduce mapping tools, it might not be that terrible, especially in Rust

Direct URI is enticing, but…. not extensible. And even medium URI is sort of ambiguous, as the input schema uri is not the output link uri for linked collections (Ownership semantics) … maybe fine either way. if the linking has to be extensible, the user will be defining that on their own in the RC anyways

• See the StackOverflow link but I don’t like the client constructing URIs