Directive ‘collection’

collection({COLL}) { ... }

Declares that a model exposes a collection of instances. {COLL} is the name of a class method or scope of the model. Generally, they are certain subsets and/or orders of the models instances.

Collections are exposed by theur URI, which has the form:

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

• https://{HOST} is a FQDN.
• {PATH} is an optional path segment (see expose parameter under: ),
• {RESOURCE} is name of the resource/model (plural form)
• {COLL} is the name the class method or scope
• {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
• max_window

The first one is to retrieve the collection the latter to create a new resource/model instance for that collection.

Note, that the special collecton :all can be exposed. The URIs https://{HOST}/{PATH}/{RESOURCE}/all and https://{HOST}/{PATH}/{RESOURCE} are both responding with all instances of the model.

POST: Does this work with certain scopes and default handler? What is the handler for non-scope collections? Custom handler required?

Windowing

Collections are always delivered partially. If not requested otherwise the items 0 to max_window (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.

Example

class Person < ApplicationRecord
  scope :johns, -> { where(first_name: 'John') }
end

expose(Person) {
  readables :first_name, :last_name
  collection(:johns) {
    via_get {
      allow do |*args|
        true # allow for all
      end
    }
  }
  collection(:all) {
    via_get {
      allow do |*args|
        true # allow for all
      end
    }
  }
}

would yield:

GET https://example.com/people:

[
    {
	"self"      : "https://example.com/people/1902",
	"first_name": "John",
	"last_name" : "Smith"
    },{
	"self"      : "https://example.com/people/23",
	"first_name": "Jakob",
	"last_name" : "Miller"
    },{
	"self"      : "https://example.com/people/87",
	"first_name": "John",
	"last_name" : "Gordon"
    }
]

GET https://example.com/people/johns:

[
    {
	"self"      : "https://example.com/people/1902",
	"first_name": "John",
	"last_name" : "Smith"
    },{
	"self"      : "https://example.com/people/87",
	"first_name": "John",
	"last_name" : "Gordon"
    }
]