Internal Insights: Approaching A Breaking Change

Hello, SKY API Community! 

We will soon make a breaking change announcement for the Constituent API to support the next generation of name formats. This breaking change will allow us to deliver the top requested endpoints for addressee and salutation management.

I want to stress that we do not take breaking changes lightly and that we deliberated a great deal before we settled on a breaking change as the best approach for this scenario. This does not mean that we will make breaking changes willy nilly across our APIs or that our current APIs are unstable. We won't, and they are not.

To be as transparent as possible, I want to draw back the curtain to show how we reached this rare decision and to open the door to any questions. For additional context and clarity, this blog post explains some metrics and considerations that we weigh when we consider breaking changes.

Workarounds

Our preferred method of change is non-breaking property additions. But when that is not an option, we prefer workarounds over breaking changes, especially when the endpoints in question are in use by anyone. For example, a workaround can use alternative naming conventions for entity models and endpoints to create a solution where both versions live side by side in an ideally non-confusing manner. However, sometimes workarounds just aren't viable for the scope of work. This is the case with name formats.

The pending enchancements for name formats include full CRUD operations, plus related endpoints such as an endpoint to get available name format types. Try as we might, we simply could not find an elegant way to surface these capabilities without running into confusing names that break the patterns we use for SKY API endpoints and entities. We therefore opted to avoid creating a confusing developer experience.

Current Usage

We never want to place undue burdens on our developers, but we must weigh the potential for improvement against the potential for disruption. We have a robust suite of instrumentation available for SKY API, so the team here at Blackbaud can dig in to see usage metrics at different tiers. For example, we can see overall SKY API traffic trends and which APIs are most popular. And we can drill down to individual endpoint calls to identify and debug problems before they are reported. Don't worry about us being too creepy though -- we only gather minimally identifying data to help monitor our performance. So we can't see the request or response payloads, although we can see the application ID, the endpoint called, and the status returned.

In the case of the existing Name format list (Single constituent) endpoint, only two applications called the endpoint during the past 90 days. Both were test apps. I reached out to the developers to ensure that they know about the breaking change and can respond appropriately, and I will do so again if another such change occurs.

Scope of Impact

Another consideration for breaking changes is the overall impact to the API. Before any breaking change, we check the number of affected endpoints and entities, and we avoid far-reaching changes if at all possible. If a plethora of endpoints and entities would experience cascading effects from a change, then we seriously reconsider (or more likely abandon) the breaking change approach. 

In this case, our desired changes only affect a single endpoint and entity if we implement before introducing the rest of the scope of name format functionality. Additionally, the included primary addressees and salutations will continue to behave as expected on the Constituent (Get) and Constituent list (Get) endpoints. So to reduce the impact, we opted to make the change sooner rather than later.

Priority and Timeliness

Given that this is the first API that I (and most of my compatriots at Blackbaud) have built out from scratch, we got a few things wrong in our v1 implementation. We plan to introduce formal versioning in the future, but breaking changes are still appropriate in some instances. We must consider a breaking change when the impact is finely scoped and so immensely valuable to our developers that it supersedes standard version iterations. Versioning will be utilized and released on a relatively standard cadence to ensure keeping up with new versions remains viable, and releases will typically include widespread changes bundled together in a single release.

Name formats is one of the unique instances when a breaking change seems appropriate. We got the list and entity model structure wrong on our first attempt, so the current implementation does not support the full management capabilities that we want to enable. In addition, the ability to manage name formats is one of our most requested features in the Constituent API. We want to deliver this high-value functionality in a timeframe that does not match our planned version increment, and we weighed that fact against the metrics and considerations described above.

I hope this post sheds some light on breaking changes and instills confidence in SKY API. I want to reiterate that breaking changes are not the norm and will not be a regular occurrence. We take these changes very seriously and avoid them at all costs.

I encourage you to use the comments section at the bottom of this post to raise questions or offer comments about this post or the related breaking change announcement. I also encourage you to keep an eye out for additional discovery topics in the Community related to the name format change. We rely on your feedback to build features that match your use cases and desired experience, so we can't do it without you!

Thanks, and as always, happy coding.