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 #can also operate in 'paged' mode: see README
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):

Offset Pagination

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 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

Paged Pagination

Paging Returned Resources:

• /users?page[number]={page_number}
• {page_number} = the page number of the resources to be returned (this is "one-based", i.e. the first page is 1, not 0)
• e.g. /users?page[number]=7 will skip the first 7 pages of user resources in the collection, and return the 8th page

Setting Page Size:

• /users?page[size]={page_size}
• {page_size} = the number of resources to be returned per page
• e.g. /users?page[size]=25 will return 25 user resources on a single page

Combining Paging/Page Sizing:

• /users?page[size]={page_size}&page[number]={page_number}
• e.g. /users?page[size]=25&page[number]=5 will skip user resources 0-100 and return resources 101-125