API Versioning at Healthie

Healthie is an API-first company and our API products are the same that our own front-end developers use to build our web and mobile apps. 

As part of our deployment process, our API team leverages versions. Versions allow you to opt-in to the latest version of our GraphQL API, ensuring that you avoid any breaking changes as we continue to deploy updates and improvements.

What is API Versioning?

API versioning is a strategy that allows developers to make updates and improvements to an API without disrupting the existing users and their applications. With versioning, different versions of an API can exist simultaneously, allowing users to choose when to adopt new changes.

How Does Versioning Work?

Versioning represents a specific version of the API. When we make updates to the GraphQL API that may result in a breaking code 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, minimizing eliminating the risk of breaking changes to your integration. 

We will continue to make non-breaking updates and improvements through accretion. This means you won't need to opt-in to use these changes, as they will be available in all versions, including the baseline. 

Benefits of Using Versioning

  1. Stability: By opting into a specific version, you ensure that your integration remains stable and unaffected by ongoing updates.
  2. Control: You have the control to decide when to adopt new features and improvements based on your schedule and readiness.
  3. Transparency: Each version is documented, providing clear insights into what has changed and how it might affect your integration.
  4. Seamless Updates: Transitioning to newer versions is straightforward, as you can review the changes in each set and prepare your application accordingly.

How to Opt-In to a GraphQL API Version

  1. Review Changes: Review the changelog below for the latest version to understand the updates and improvements included.
  2. Testing: Test the new version in your development environment to ensure compatibility and address any potential issues.
  3. Opt-In: Update your API requests to specify the desired version. Tell us what version you want us to serve via an HTTP header. 

Example: curl -v -H "Healthie-GraphQL-API-Version: 2024-08-01" -H 'AuthorizationSource: API' -H 'Authorization: Bearer ...' -d '{...}' https://api.gethealthie.com/graphql

2024-08-01  is the current version available.

If you have any questions or need assistance, our support team is here to help at hello@gethealthie.com.

Versions

2024-08-01

  • Standardize the GraphQL type used for datetimes in the Healthie API to all be ISO8601DateTime objects (vs String)
  • Standardize the GraphQL type used for IDs to always to be ID (Vs String and Int)
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.