Developer Center
Getting Started
Using Jobber’s API
Building Your App
Publishing Your App
App Template Project
Custom Integrations
Changelog
Terms of Service

API Versioning

API versioning allows Jobber to continuously evolve our platform and capabilities while offering third-party developers a predictable path for feature upgrades and deprecations.

Our Approach

  • Dangerous and breaking changes will be added in versioned releases
  • Versions will be in date format (YYYY-MM-DD), and will be published to our changelog at irregular intervals
  • Versions will be added irregularly whenever a breaking or dangerous change is made to our API
  • Old versions will be supported for 12 months following the release date of a newer version
  • When using a version which becomes unsupported, you will be automatically upgraded to the earliest supported version (even if it includes breaking changes, which could impact your app)
    • In addition, you may receive automated or manual communications to upgrade, or encounter brownouts where the version will not be available.

Example version support schedule

How to Specify a Version

To specify a version, you must use the X-JOBBER-GRAPHQL-VERSION HTTP header and set it to one of our active versions. Specifying a version in the header is required for all apps.

Version Information

The response will include information about the API version your request is making.

  • If you are requesting a version that will removed in the next 3 months, a warning will be returned with information on when the version will be removed.
  • If you are requesting a historic version that is unsupported, your request will be automatically upgraded to the earliest supported version. This version will be returned under the version key.

Version information is found under the extensions key:

  "versioning": {
      "version": "2022-04-29",
      "warning": "API version 2022-04-29 is scheduled to be removed on May 13, 2023, please upgrade as soon as possible.
                  For more information: https://developer.getjobber.com/docs/using_jobbers_api/api_versioning"
    }

How to Upgrade to a Newer Version

We recommend you use the most recent active API version to benefit from bug fixes and schema improvements.

To upgrade to a newer API version, consult the changelog to look for any breaking changes, which could impact your application. If you're using automatic code generation and type checking (such as with codegen), it could provide hints to what has broken.

In some cases, we will deprecate fields before they're removed and give alternate fields, which could satisfy your use case.

Deprecation Notice

Once you've confirmed the new version works with your application (through manual and automated testing), update the X-JOBBER-GRAPHQL-VERSION header value in your production environment.