API Versioning

Understanding how versioning works in the Mahalo Health API and how to ensure your integrations remain compatible.

Versioning Strategy

The Mahalo Health API uses a path-based versioning strategy. All API endpoints are prefixed with a version identifier (e.g., /v1/) to ensure backward compatibility as the API evolves.

Current Versions

VersionStatusReleasedEnd of Life
v1CurrentJanuary 2023Not scheduled
betaDeprecatedJune 2022June 2023

Version Selection

You can specify which API version to use by including the version in the URL path:

# Current stable version
GET https://api.mahalo.health/v1/patients

# Deprecated beta version
GET https://api.mahalo.health/beta/patients

Versioning Policy

Our versioning policy is designed to provide stability while allowing the API to evolve:

  • We will not make breaking changes to existing API versions
  • We may add new features to existing API versions in a backward-compatible way
  • When we need to make breaking changes, we will release a new API version
  • We provide at least 12 months notice before deprecating an API version
  • Deprecated versions will continue to function until their end-of-life date

Breaking vs. Non-Breaking Changes

Breaking ChangesNon-Breaking Changes
  • Removing an endpoint
  • Removing a field from a response
  • Changing a field's data type
  • Adding a required request parameter
  • Changing error codes or response formats
  • Adding new endpoints
  • Adding new fields to responses
  • Adding optional request parameters
  • Improving performance
  • Bug fixes that don't change behavior

Version Migration

When a new API version is released, we provide detailed migration guides to help you update your integrations. These guides include:

  • Summary of changes between versions
  • Step-by-step migration instructions
  • Code examples for common use cases
  • Testing recommendations

For the latest migration guides, please refer to our Migration Guides section.