Module: APIResourceIncludable

Extended by:
ActiveSupport::Concern
Included in:
API::APIDataManagement, API::Open, API::V1
Defined in:
app/api/concerns/api_resource_includable.rb

Overview

Helper To Make Resource APIs Includable

Inclusion of related resource lets your API return resources related to the primary data. This endpoint will support an include request parameter to allow the client to customize which related resources should be returned.

This design made references to the rules of Inclusion of Related Resources in JSON API: jsonapi.org/format/#fetching-includes

For instance, comments could be requested with articles:

GET /articles?include=comments

The server will respond

[
  {
    "id": 1,
    "title": "First Post",
    "content": "...",
    "comments": [
      {
        "id": 1,
        "content": "..."
      },
      {
        "id": 3,
        "content": "..."
      },
      {
        "id": 6,
        "content": "..."
      }
    ]
  },
  {
    "id": 2,
    "title": "Second Post",
    "content": "...",
    "comments": [
      {
        "id": 2,
        "content": "..."
      },
      {
        "id": 4,
        "content": "..."
      },
      {
        "id": 5,
        "content": "..."
      }
    ]
  }
]

instead of just:

[
  {
    "id": 1,
    "title": "First Post",
    "content": "...",
    "comments": [1, 3, 6]
  },
  {
    "id": 2,
    "title": "Second Post",
    "content": "...",
    "comments": [2, 4, 5]
  }
]

If requesting multiple related resources is needed, they can be stated in a comma-separated list:

GET /articles/12?include=author,comments

Usage

Include this Concern in your Grape API class:

class SampleAPI < Grape::API
  include APIResourceIncludable
end

then set the options for the inclusion in the grape method:

resources :posts do
  get do
    inclusion_for :post, root: true    # ...

  end
end

Further usage of inclusion_for method can be found in the docs of the HelperMethods class.

This helper parses the include and include[object_type] parameters to determine what the API caller wants, and save the results into instance variables for further usage.

After this you can use the inclusion helper method to get the inclusion data that the request specifies, and do something like this in your controller:

resource = resource.includes(:author) if inclusion(:post, :author)

The inclusion helper method returns data like this:

inclusion #=> { post: [:author] }
inclusion(:post) #=> [:author]
inclusion(:post, :author) #=> true

API View with RABL

If you're using RABL as the API view, it can be setup like this:

# set the includable and default inclusion fields of the view
set_inclusion :post, default_includes: [:author]

# set the details for all includable fields
set_inclusion_field :post, :author, :author_id

# extends the partial to show included fields
extends('extensions/includable_childs', locals: { self_resource: :post })

Defined Under Namespace

Modules: HelperMethods

Class Method Summary collapse

Class Method Details

.include_param_desc(example: nil, default: nil) ⇒ Object

Return the 'include' param description


196
197
198
199
200
201
202
203
204
205
206
207
# File 'app/api/concerns/api_resource_includable.rb', line 196

def self.include_param_desc(example: nil, default: nil)
  if default.present?
    desc = "Returning compound documents that include specific associated objects, defaults to '#{default}'."
  else
    desc = "Returning compound documents that include specific associated objects."
  end
  if example.present?
    "#{desc} Example value: '#{example}'"
  else
    desc
  end
end