v2 Migration Guide

Leverage this guide to migrate from the v1 API to the v2 API

Suggest Edits

Overview

We're excited to announce the release of the second version of the Buoy Symptom Checker API! 🎉

This migration guide will allow you to easily identify the changes that API clients will need to implement in order to migrate to v2. In this release, we've moved the API to a versioned structure. Going forward, we plan to release most breaking changes in new API versions. We've also simplified several request and response bodies. Additionally, we've released an updated API reference and new documentation.

Migration timelines

We're planning to release the v2 API to the sandbox environment on or around July 11, 2021. API clients must migrate to the v2 API in Production by August 20, 2021. The v1 API will be fully deprecated in early Q4 2021.

❗️

Work with your Buoy technical project manager before migrating code changes to production

We're enabling production access on a client_id basis. Please work with your Buoy technical project manager to confirm Production access before migrating code changes to your production environments.

Change Reference

All required and optional changes are outlined in the sections below. Required changes are marked by the presence of must within the change description.

Base URL

We've updated the base URL to an API specific subdomain. API clients must update the base URL used in all requests.

EnvironmentOld base URLNew base URL
Sandboxsandbox.buoyhealth.com/api/api.sandbox.buoyhealth.com/symptom-checker/v2/
Productionwww.buoyhealth.com/api/api.buoyhealth.com/symptom-checker/v2/

Authorization

We've update our audience used in access token retrieval requests to https://auth.sandbox.buoyhealth.com/oauth/token/ (sandbox) or https://auth.buoyhealth.com/oauth/token/ (production). API clients must use the updated audience value.

EnvironmentOld audience valueNew audience value
Sandboxhttps://sandbox.buoyhealth.com/api/https://api.sandbox.buoyhealth.com
Productionhttps://buoyhealth.com/api/https://api.buoyhealth.com

API clients should continue to pass grant_type, client_id, and client_secret unchanged. 

curl --request POST \
  --url https://auth.sandbox.buoyhealth.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"<client_id>","client_secret":"<client_secret>","audience":"https://sandbox.buoyhealth.com/api/","grant_type":"client_credentials"}'

curl --request POST \
  --url https://auth.sandbox.buoyhealth.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"<client_id>","client_secret":"<client_secret>","audience":"https://api.sandbox.buoyhealth.com","grant_type":"client_credentials"}'

Request Bodies

We've simplified several request bodies.

  • Complaints: We've removed the extra field. API clients must omit the extra field with requests to either the create complaint or update complaint endpoints.
  • Intents: We've removed the detail and context fields. API clients must omit the detail and context field when using the create intent or update intent endpoints.
  • Questions: We're made the extra field optional for single-select (S-type) and multiple-select (M-type) questions. API clients no longer need to submit an empty string in the extra field when using the update question endpoint. Duration-response (D-type) questions still require that the extra field contain the duration in hours. 
// For M-type and S-type questions either style is now acceptable:
// Option 1: Empty string in extra field
{
  "token": "<AnswerToken3>",
  "extra": ""
}
// Option 2: Extra field ommited
{
  "token": "<AnswerToken3>"
}

// For D-type questions, a duration in hours is still required:
{
  "token": "<AnswerToken3>",
  "extra": "4"
}

Response Bodies

We've simplified several response bodies.

  • Interviews: We've removed profile.race, profile.height, profile.weight, profile.bmi, marketplace, and variant.
  • Complaints: We've removed the extra field.
  • Intents: We've removed the detail and context fields.
  • Questions: We've removed answer options where pre-selected values were non-null. API clients no longer need to filter pre-selected answer options from user display. Additionally, the preselected field has been removed from all responses.
  • Results: We've removed the advice and test fields.

Updated over 2 years ago