Directive ‘association’

association({ASSOC}) { ... }

Declares that an association of the model is to be exposed. {ASSOC} is the name of an association of the has_one, has_many, belongs_to or a has_and_belongs_to_many type.

Associations are exposed by their URI, which has the form:

https://{HOST}/{PATH}/{RESOURCE}/{ID}/{ASSOC}?{PARAMS}, where

• https://{HOST} is a FQDN.
• {PATH} is an optional path segment (see expose parameter under: ),
• {RESOURCE} is name of the resource/model
• {ID} is a string of digits: [0-9]+,
• {ASSOC} is the name the association
• {PARAMS} is an optional list of query parameters

Within the block it must be declared which methods the exposed URI accepts. This is done by the directives which have further sub-directives for permissions and custom handlers:

• via_get
• via_post
• via_link
• via_unlink
• max_window

Note that the HTTP methods PATCH and DELETE are not possbile for association URIs. These are used for canonical URLs of model instances only.

Plural Associations

For plural associaitons (has_many, has_and_belongs_to_many) the methods GET, POST, LINK and UNLINK are available. A GET response carries always a JSON Array of Objects representing model instances. POST will create a new resource/model instance and associates it with the base resource/model. LINK and UNLINK will associate or disassociate roesources/models. See the via_* directive pages for mote details.

Windowing

Plural associations are always delivered partially. If not requested otherwise the items 0 to max_window - 1 (default is defined in the global configuration file) are delivered. To request other ranges the HTTP header Range should be used. More on the max_window page.

Singular Associations

On singluar associaitons (has_one, belongs_to) the methods GET, LINK, UNLINK are available. A GET response will deliver the JSON representation of a model instance, LINK/UNLINK associate other resources or remove the association.

Singular associated resources/models cannot be updated via their association URIs to avoid ambiguities. Use the canonical URL of the recource (self property) to use with PATCH.

Example

expose(Person) {
  readables :first_name
  association(:friends) {
    via_get {
      allow do |*args|
        true # allow for all
      end
    }
  }
}

would yield a JSON representation:

{
    "self"      : "https://example.com/people/42",
    "first_name": "Jason",
    "friends"   : "https://example.com/people/42/friends"
}

The HTTP API provides read access to a collection of “friend” records, which are delivered as a JSON array:

GET https://example.com/people/42/friends:

[
    {
	"self"      : "https://example.com/people/1902",
	"first_name": "John",
	"friends"   : "https://example.com/people/1902/friends"
    },
    {
	"self"      : "https://example.com/people/23",
	"first_name": "Jakob",
	"friends"   : "https://example.com/people/23/friends"
    }
]