Directive ‘via_link’

via_link { ... }

The directive activates the routing of LINK requests to the application. LINK requests update link meta data of a resource. I.e an association is establish between two existing resources.

via_link may appear inside the block of directive association.

The directive’s block contains allow (required) and handler directives (optional), which define run-time code to decide on authorization and contain custom business logic if the built-in default handlers are not appropriate.

The LINK-requests URI must be that of an association (a.k.a context IRI) and the HTTP header Link must contain the URI of the resource to be linked to the association (a.k.a target IRI). The relation type should be related as defined in RFC 4287 The Atom Syndication Format.

See also RFC 5988 Web Linking

See also this note on LINK and UNLINK

Example

expose(Person) {
  readables :first_name, :last_name
  association(:country) {
    via_get {
      allow do |*args|
        true
      end
    }

    via_link {
      allow do |*args|
        true
      end

      ## implicit handler
      # handler do |source, target, uri_params|
      #  source.country = target
      #  source.save!
      # end
    }
  }
}

expose(Country) {
  readables :name, :languages
  via_get {
    allow do |*args|
      true
    end
  }

  association(:people) {
    via_get {
      allow do |*args|
        true
      end
    }

    via_link {
      allow do |*args|
        true
      end

      ## implicit hander
      # handler do |source, target, uri_params|
      #  source.people << target
      # end
    }
  }
}

Request:

LINK https://example.com/people/102/country
     Link: <https://example.com/countries/40>; rel="related"

Response: 200 OK

Request:

GET https://example.com/people/102/country

Response:

{
    "self"      : "https://example.com/countries/40",
    "people"    : "https://example.com/countries/40/people",
    "name"      : "Switzerland",
    "languages" : ["fr","de","it"]
}

---

Request:

LINK https://example.com/countries/40/people
     Link: <https://example.com/people/44>; rel="related"

Response: 200 OK

Request: GET https://example.com/countries/40/people

[
    {
	"self"      : "https://example.com/people/44",
	"country"   : "https://example.com/people/44/countries",
	"first_name": "Johnny",
	"last_name" : "Gold"
    } , ...
]