Backwards Compatibility

Before we deploy our code to production, we want to ensure we aren’t introducing any backwards incompatibilities that will break existing clients. Of course, tests are our first line of defense here. But a developer could always simply update the test and introduce a backwards-incompatibility. This is why JSONAPI Suite comes with an additional backwards-compatibility check you can run in your Continuous Integration pipeline.

In the course of writing our application, we autodocumented with Swagger. That means our swagger.json is effectively a schema - a definition of attributes, types, query parameters and payloads. We can compare the swagger.json of a given commit to what’s running in production to see if any backwards-incompatibilities were introduced.

If you used our generator to set up your application, you’ll have noticed this line added to Rakefile:

require 'jsonapi_swagger_helpers'

This allows us to run the rake task

rake swagger_diff['my_api','http://example.com']

This task will:

• Pull down the schema from http://example.com/my_api/swagger.json.
• Compare it to the swagger.json generated locally.

This uses swagger-diff underneath the hood. You’ll get helpful output noting any missing filters, incorrect types, or other backwards incompatibilities.