Skip to content
API Docs

Versioning

At Healthie, we’re committed to providing a stable and reliable API for all our integrations. Our versioning strategy allows us to continuously improve our API while ensuring your existing integrations remain functional. When we need to make breaking changes, we release a new API version, giving you complete control over when to adopt these changes.

Understanding Breaking Changes

A breaking change is any modification that could cause existing API calls to fail or return different results without any changes to your account data. We take breaking changes seriously and use versioning to ensure they never affect your integration unexpectedly.

Examples of breaking changes (which require a new version):

  • Removing a field
  • Changing the return type of a field
  • Changing an input argument default (e.g changing a query to be default unpaginated versus paginated)
  • Making a field nullable when it was previously non-nullable
  • Making an input argument non-nullable when it was previously nullable (e.g. id: ID -> id: ID!)
  • Making a field nullable when it was previously non-nullable (e.g. user: User! -> user: User)

Examples of non-breaking changes (which we can make without a new version):

  • Adding new queries, mutations, or fields
  • Adding an optional new input argument to an existing mutation
  • Adding a new filter or sort_by option to an existing field
  • Adding new and updated data to Healthie-provided resource queries (e.g Insurance Plans or Icd Codes)
  • Fixing an internal server error (e.g a 500)

When we need to make breaking changes, we release a new API version. This allows you to continue using your current version while giving you the option to adopt the new changes when you’re ready.

What is API Versioning?

API versioning is a strategy that allows us to make significant improvements to our API while protecting your existing integrations. Different versions of our API can exist simultaneously, giving you control over when to adopt new changes. This approach ensures we can continue evolving our API while maintaining stability for all our users.

When will Healthie release a new version?

When we make updates to the GraphQL API that may result in a breaking change, a new version is created. Each version is carefully documented and includes all the modifications made since the last version. By opting into a specific version, you can control when and how you adopt new features and changes, eliminating the risk of breaking your existing integration.

All API versions are cumulative, which means that changes in version N+1 will include all changes from version N. Customers that request the latest version will need to update their API clients as we release new versions.

Specifying an API Version

Terminal window
curl \
-H "Healthie-GraphQL-API-Version: 2024-06-01" \
-H 'AuthorizationSource: API' \
-H 'Authorization: Bearer ...' \
-d '{...}' https://api.gethealthie.com/graphql

You should use the Healthie-GraphQL-API-Version header to specify an API version, as shown in following example.

Requests without the Healthie-GraphQL-API-Version header will default to use the 2024-06-01 version (baseline).

How to adopt a new version

  1. Review Changes: Check the changelog below for updates in the latest version. Use the GraphQL Explorer and check our Schema Reference to find the latest schema definitions for the version you are adopting.
  2. Test: Try the new version in your development environment to ensure compatibility
  3. Update: Change your API requests to use the new version header
  4. Deploy: Roll out your updated integration with confidence

Version History

2024-11-01 (Latest)

  • Added validation and updated non-nullability for common mutations
  • Fixed spelling issues across the API

2024-10-20

  • Updated ISO601Date and ISO601DateTime types

2024-10-01

  • Added pagination to the pharmacies query field

2024-07-01

  • Standardized the GraphQL type used for datetime in the Healthie API to all be ISO8601DateTime types (vs String)
  • Standardized the GraphQL type used for IDs to always to be ID (vs String and Int)