Principles for Developing with Herald

At Herald we believe having a shared reality with our collaborators will lead to fewer errors and faster implementation.

At Herald we experience Hyrum’s law of software development a lot (as developers and consumers of APIs): With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody (you can read the original essay here). We are making an API for you from many institution APIs. We’re always thinking about keeping our software working, so we can keep yours working. That means dealing with changes.

‍

Upcoming High Impact Changes

We currently have one High Impact Change scheduled for August 31, 2024. This changes how quotes and files are processed, greatly reducing the time in which Herald can provide quotes. If this change impacts you, you'll be contacted by our Customer Support team.

‍

API Changes at Herald

At Herald, we want our development partners to build with principles, not rules. So we’re going to set out for you a vision of how our partnership should work, and give you the flexibility to choose how to get there.

Herald changes fall into two groups:

Standard Operating Changes: the sort of changes we release often as Herald continues to grow and improve. Herald releases new code about once every two weeks.
High Impact Changes: the sort of changes that are risky for your integration stability and should be treated with care. We actively strive to minimize this type of change. These are essentially breaking changes.

As a developer who is working with Herald we want you to build in a way that is ready for our Standard Operating Changes, and be ready to work with us when High Impact Changes happen.

Let’s look at some detailed examples so you can be prepared for Standard Operating Changes, and so that you can know what Herald considers a High Impact Change.

Resource or Concept	👌 Standard Operating Changes	🚨 High Impact Changes
Endpoints	Adding a new endpoint to expand capabilities of our API	Removing or changing an existing endpoint
Requests	Adding new, optional Key Value Pairs	Adding new, required Key Value Pairs, or Removing Key value pairs
Requests	Adding new Key Value Pairs	Removing Key value pairs
Applications	Adding or removing questions (parameters)
Files	Adding new file types to our responses	Removing file types
Statuses	Adding Transitions from one status type to another	Adding or removing statuses
Validation Rules	Making validation rules more permissive	Making a validation rule stricter

‍

High Impact Changes

As you saw above, High Impact Changes come with risk to your implementation stability. We endeavor to minimize these types of changes, but they do happen as we offer enhanced features. When Herald makes a high impact change we know our clients will need time to prepare.

[.icon-alert][.icon-alert] Ensuring that you have sufficient time to update your integration to avoid a breaking change in production is our top priority. We're willing to extend our testing periods as needed to meet your needs.