Includes

The include query parameter controls which associations appear in API responses.

For association configuration options like writable, filterable, and polymorphic support, see Associations.

Query Format

GET /posts?include[comments]=true

Structure: include[association]=true

Multiple associations:

GET /posts?include[comments]=true&include[author]=true

Nested Includes

Include associations on associations:

GET /posts?include[comments][author]=true

This includes comments and each comment's author.

Representation Configuration

Associations configure their default include behavior in the representation:

class PostRepresentation < Apiwork::Representation::Base
  has_many :comments
  has_many :tags
  belongs_to :author, include: :always
end

Option	Behavior
include: :optional	Included only when requested (default)
include: :always	Always included in responses

Optional (default)

has_many :comments, include: :optional  # Can be omitted — optional is default

Associations are optional by default. They only appear when requested:

GET /posts/1                          # No comments
GET /posts/1?include[comments]=true   # With comments

Always Include

belongs_to :author, include: :always

The author appears in every response.

INFO

Associations with include: :always cannot be excluded. This guarantees the type in generated exports.

Response Shape

Without includes:

{
  "post": {
    "id": "1",
    "title": "Hello World"
  }
}

With include[comments]=true:

{
  "post": {
    "id": "1",
    "title": "Hello World",
    "comments": [
      {
        "id": "1",
        "content": "Great post!"
      },
      {
        "id": "2",
        "content": "Thanks!"
      }
    ]
  }
}

Depth Limit

The adapter generates nested include parameters up to 3 levels deep. This prevents infinite type generation from circular associations (e.g., Invoice to Items to Invoice to Items). Beyond 3 levels, deeper associations fall back to boolean parameters.

GET /posts?include[comments][author][company]=true    # 3 levels — OK

Within the limit, circular references are detected individually — the adapter falls back to a boolean parameter for the specific association that forms the cycle.

Polymorphic Associations

Polymorphic associations support boolean includes only — no nested shape:

GET /posts?include[commentable]=true    # Boolean — OK

Nested includes on polymorphic associations are not supported because the target representation varies at runtime.

N+1 Prevention

The adapter eager loads associations to prevent N+1 queries. When filtering by an association, the adapter also eager loads it to avoid N+1 in the filter query.

See also

• Include Modes — configuring :optional and :always
• Association Declaration — association options