Upgrade Guide

Upgrading Gemfile

gem 'jsonapi-resources', '~> 0.10.0'

# Use alpha level code at your own risk
# gem 'jsonapi-resources', git: 'https://github.com/cerebris/jsonapi-resources.git', branch: 'master'

And then execute:


Check for known upgrade issues

Run the jsonapi:resources:check_upgrade rake task:

rake jsonapi:resources:check_upgrade

This will look for overrides in your existing resources that will no longer be called by JR.

Fix the resources detected by the check


The find_records method has been removed and the functionality has been moved to other methods. It’s recommended that you use the apply callable on filters and sorts, and the apply_join callable on relationships.


While the records method has not been changed some of the overrides that were needed for custom app logic may need to be reconsidered. One area in particular is joining or including to_many relationships. If this can’t be avoided it is recommended that a distinct call be added to the relation.

The new configuration option warn_on_performance_issues is designed to catch this state.


The records_for method has been removed. Related records should now use the apply_join callable on relationships.


The apply_includes has been removed. Because related resources are no longer loaded using the rails auto-generated association methods the need for includes to prevent N+1 query execution has been removed. If you need includes for a resource, say for a calculated attribute using a value on a related model, you can add the call to includes in an override of self.records.


The Processor class has changed significantly in how it builds the request’s result. For show and index requests the Processor works with the resource finder to first find the identifiers and optional cache fields for the primary and included resources, represented as a ResourceFragment. If a resource enables caching the cached resources are pulled for those resources without changes. Finally the full resource set is populated from the data source for any cache misses. The ActiveRelationResourceFinder uses pluck for the first stage to get the identifiers and cache fields. This avoids the overhead of model instantiation for cache hits.

If you have created custom processors or overridden features you will need to update these.


Prior to release v0.10 JR performed queries slightly differently depending on whether caching was enabled. This is effectively no longer the case, besides the additional requirement to fetch the cache field the queries are the same.

Additional steps

this will be updated as needed

Please report issues you encounter upgrading either at Gitter or Github