Fieldsets

View the JSONAPI specification

View the JS Documentation

Sparse Fieldsets

You’ll get this for free. Given a serializer:

# app/serializers/serializable_post.rb
class SerializablePost < JSONAPI::Serializable::Resource
  type :posts

  attribute :title
  attribute :description
  attribute :comment_count
end

And the request:

/posts?fields[posts]=title,comment_count

The description field will not be returned in the response.

Extra Fieldsets

View the YARD documentation

The opposite of a “sparse fieldset” is an “extra fieldset”. Perhaps you have an attribute that is computationally expensive and should only be returned when explicitly requested. Perhaps the majority of your clients need the same fields (and can share the same cache) but one client needs extra data (and you’ll accept the cache miss).

To request an extra field, just specify it in your serializer:

# app/serializers/serializable_employee.rb

extra_attribute :net_worth do
  1_000_000
end

In the URL, replace fields with extra_fields:

/posts?extra_fields[employees]=net_worth

The net_worth attribute will only be returned when explicitly requested.

You may want to eager load some data only when a specific extra field is requested. There’s a hook for this in your Resource;

# app/resources/employee_resource.rb

extra_field(employees: [:net_worth]) do |scope|
  scope.includes(:assets)
end