JSONAPI::Resources Querystring Examples

Overview

The purpose of this article is to correlate querystring parameter usage in jsonapi-resources with the jsonapi specification

Examples

Given the example resource:

class UserResource < JSONAPI::Resource
  attribute :first_name
  attribute :last_name
  attribute :email
  attribute :created_at
  attribute :updated_at

  paginator :offset
end

and the following route (in routes.rb):

jsonapi_resources :users

we can do the following:

Fields

In the case where you don't need all the attributes to be returned, you can request specific attributes be returned.

Limiting Returned Resource Attributes:

• /users?fields[{resource-type}]={attribute-names}
• {resource-type} = the pluralized type of model whose attributes you wish to limit (must be dasherized)
• {attribute-names} = a comma separated list of the attributes you wish to be included (must be dasherized)
• e.g. /users?fields[users]=first-name,last-name will return user resources including only the first_name and last_name attributes

Sorting

Ascending By A Property:

• /users?sort={attribute-name}
• {attribute-name} = the attribute you wish to sort by (must be dasherized)
• e.g. /users?sort=last-name will sort the collection ascending by last name (A-Z)

Descending By A Property:

• /users?sort=-{attribute-name}
• the sort parameter is prepended by a -
• {attribute-name} = the attribute you wish to sort by (must be dasherized)
• e.g. /users?sort=-last-name will sort the collection descending by last name (Z-A)

Pagination

Provided pagination has been enabled for your application or resource (see README.md):

Limiting Returned Resources:

• /users?page[limit]={resource_count}
• {resource_count} = number of resources you want returned
• e.g. /users?page[limit]=5 will return the first 5 user resources

Offsetting/Paging Returned Resources:

• /users?page[offset]={resource_offset}
• {resource_offset} = the number of records to offset by prior to returning resources
• e.g. /users?page[offset]=10 will skip the first 10 user resources in the collection

Combining Limiting/Offsetting:

• /users?page[limit]={resource_count}&page[offset]={resource_offset}
• e.g. /users?page[limit]=5&page[offset]=10 will skip user resources 0-10 and return resources 11-15