Upgrading from JSONAPI Suite
The early version of Graphiti was JSONAPI Suite. If you are a JSONAPI Suite user, here’s how to upgrade your existing API.
The work here is mostly consolidating logic that currently lives in multiple files into a single Resource, and rewriting specs. The good news is that, because we emphasize full-stack integration tests, we can perform the upgrade with confidence by ensuring our tests pass.
Before You Start
There is no Swagger UI equivalent for Graphiti. Swagger is a poor fit for graph APIs, and we instead rely on a custom Graphiti Schema. Instead, check out Vandal.
Start by removing the gems
swagger-diff. You’ll eventually remove
jsonapi_spec_helpers, but keep it for now.
responders. See the
Sample App Gemfile.
and the Swagger UI that lives under
Remove swagger helpers from
JsonapiErrorable and change to
spec/rails_helper.rb correct (though keep
for now). See sample.
At this point, running your specs should give you a lot of errors like
"index" not found.
Upgrade your ApplicationController.
Upgrade your ApplicationResource.
- Note that this references
Rails.application.routes.default_url_options[:host]. That’s set in config/application.rb.
- Note the
endpoint_namespace. Make this match your current routes.
ApplicationResource.endpoint_namespacein your routes file.
Begin rewriting your Resources. Go through
spec/payloads and add these
attributes/types to the Resource. Remember to mark these as
writable: false, etc. Look at
config/initializers/strong_resources.rb to see if an attribute should
allow_filters. If it’s a one-liner, just make sure
there is a corresponding attribute. If there is custom logic:
Two things about filters: by default,
value is now always array. Pass
single: true if your logic only supports a single value. Also: a
filter with a given type now comes with operators -
suffix, etc. If you don’t support these, limit operations
Note that we now support multiple content types for read requests:
.xml. If you have any clients explicitly putting
at the end of the URL, they are now going to get a simple JSON response
instead of JSONAPI. Avoid the responders gem if you don’t want this.
You may want to move some persistence logic to before_commit.
Resources now have #base_scope. If you previously were using
default_filter or passing in a custom scope in your controller, consider moving to
If you have manual sideloading logic with scope, it is highly
recommended you rewriting using
params - see relationship docs. If you do still need
scope, it now yields the parent ids as the first argument and the actual parent models as the second.
Finally, you are encouraged to avoid overriding
directly. Instead, override
delete, and use
At this point, get all your
spec/legacy specs passing.
When you’re done, generate the new Resource and API Specs. Note that much of this is syntax changes, you can copy/paste large amounts of logic from
spec/legacy. To ease this process, try
rails g graphiti:api_test PostResource and
rails g graphiti:resource_test PostResource.
You should now have the upgraded and legacy test suite working. We can now remove the legacy specs:
rm -rf spec/payloads
rm -rf spec/legacy
And you’re done! Deploy to a staging environment and verify your API supports all your real-world scenarios.
Though you can get specs passing with your existing
etc, try to rewrite them using hooks. It’s no longer considered a best
practice to override these methods because you’ll be bypassing hooks.
Instead, add hooks and override
def save(model) if you need to.
respond_with in read operations and
render jsonapi: in write
operations. This is because the
responders gem bypasses renderers for
PUT, and a few other minor issues.