Overview

The Medallion API is actively developed as we expand our platform capabilities. In some cases this can lead to backwards incompatible changes which have the potential to break your API integration. In these cases you will need to update your integration to accommodate the breaking change. To simplify your update process, our breaking changes will be released as dated versions. When making a request you can specify your version in the request header.

import requests

url = "http://localhost:8000/api/v1/org/providers/"

headers = {
    "Accept": "application/json",
    "x-api-key": "APIKEY",
  	"x-api-version": "2023-12-01"
}

response = requests.get(url, headers=headers)

When a new version is released you should update your integration by sending the new dated version as the x-api-version header to all your requests. This will ensure that you are seeing the new behavior in your requests and responses. You can then test your integration, resolve any errors, and release your changes safely. For example if the start_date field in the GET Providers was updated to employment_start_date on Nov 11, 2023. A pre-existing integration to get providers with future start dates might look like the following:

import requests
from datetime import datetime

url = "http://localhost:8000/api/v1/org/providers/"

# Current integration requesting the previous version from Oct 2, 2023
headers = {
    "Accept": "application/json",
    "x-api-key": "APIKEY",
  	"x-api-version": "2023-10-02"
}

response = requests.get(url, headers=headers)
response.raise_for_status()

response_json = response.json()
results = response_json['results']

# Notice that start_date is not None
print(results[0].get('start_date'))

providers_not_started = [provider['id'] for provider in results if provider['start_date'] > datetime.now()]

An updated integration could look like this:

import requests

url = "http://localhost:8000/api/v1/org/providers/"

# Adopting the new change by updating the API version to its release date Nov 11, 2023"
headers = {
    "Accept": "application/json",
    "x-api-key": "APIKEY",
  	"x-api-version": "2023-11-11"
}

response = requests.get(url, headers=headers)
response.raise_for_status()

response_json = response.json()
results = response_json['results']

# Notice that start_date is None
print(results[0].get('start_date'))

providers_not_started = [provider['id'] for provider in results if provider['employment_start_date'] > datetime.now()]

Each dated version will have a removal date indicated in the Changelog and notification email. After the removal date, the changes made in that version will become standard across all versions. If you are requesting a version that has reached it's removal date your request will still be fulfilled but your integration may have errors if it is relying on fields or behavior that have been removed in a later version.

What is Backwards Compatibility?

We define backwards compatibility as any change that does not remove or materially change any existing API behavior. Backwards compatible changes include:

• Adding a new API resource
• Adding a new optional request query or body parameters
• Adding a new field to a response
• Adding a new response type

Keeping Track of API Changes

We will notify you of new API versions and upcoming breaking changes through several channels. As soon as a change is released the API Reference will reflect the new behavior. In addition, we will create a Changelog entry detailing the changes as well as the version release and removal dates. Finally, we will send an email notification to the technical contact(s) you have identified with details about how to update your implementation.