API Schema

This learning is based on a real production incident that affected customers.

Let’s examine how review API schema changes, using a real-world example where a misconfigured schema affected FX quotes.

The Scenario

A misconfigured API/GraphQL contract schema caused an outage in Circle Mint, affecting FX quotes.

The expiry date was incorrectly marked as required for reference quotes.
Manual testing did not cover accounts with FX trading enabled.
Unit tests were flawed due to assumptions in the mock data.
Lack of automated end-to-end tests for critical flows.
The review process did not catch the configuration gaps.

Before

FxApi.types.ts


export interface Quote {
  id: string
  rate: number
  from: BaseApiType.CircleApi.Amount
  to: BaseApiType.CircleApi.Amount
  expiry: string
}

FxApi.transform.ts


public static transformFxQuote(
  quote: CircleApi.Fx.Quote,
): DataSource.Fx.Quote {
  return {
    ...quote,
    expiry: BaseApiTransform.stringToDate(quote.expiry),
  }
}

PR Comment

Choose the comment that you think is the most constructive and helpful.

Fleur Ivorycommented on Apr 2, 2025

The changes look good.

Yolanthe Coffeecommented on Apr 2, 2025

Looks good. We can double check if the external API payloads at a later time.

Marylin Fuchsiacommented on Apr 2, 2025

The changes look good. The API document doesn’t seem to fully define some of the fields. We can try it out by hand before merging to verify the payload.

Melodee Amethystcommented on Apr 2, 2025

Thanks for implementing the FX quoting! Before we merge, let’s ensure we understand the full product impact:

It seems like there needs to be some more clarity into the FX API and the response it produces. We’ll need to confirm before we merge.
Can we double check the format of expiry? string can be ambiguous at times
Mocked tests are good for development, but since the changes references another service, E2E tests would be preferrable.
We’ll want to make sure the E2E tests run periodically in case there are changes on the external API.
It would be best to give this a dogfooding session to see if there’s any timing issues around the expiry

This will help us catch any unintended consequences before deployment.

Click here to learn more

Key Lessons

1. API Contract Management

Clearly specify optional and required fields in API contracts
Follow up on integration details to avoid assumptions
Regularly review and update API documentation
Implement checks to prevent breaking changes in API contracts

2. Testing and Quality Assurance

Perform smoke tests on feature sets sharing common APIs
Develop comprehensive end-to-end tests for critical flows
Include various feature flags in automated tests
Regularly update and review test data and scenarios

3. Incident Detection and Response

Ensure manual testing includes an exhaustive list of configurations
Quickly identify and resolve issues once detected
Use automated alerts to detect issues faster
Maintain clear communication channels during incidents

Tips for Reviewers

1. API Contract Clarity

Confirm that API contracts clearly specify optional and required fields
Ensure follow-ups on integration details to avoid assumptions
It’s better to confirm than to assume
Example: “Are all optional fields clearly marked in the API contract?“

2. Comprehensive Testing

Verify that smoke tests cover feature sets sharing common APIs
Ensure comprehensive end-to-end tests for critical flows
Example: “Do we have E2E tests that covers all critical flows?“

3. Check the documentation

Double check the documentation the PR was based on
Don’t assume the PR description is fully correct
Example: “Can you link the references in the documentation for the changes?”

Common Pitfalls to Avoid

1. Making assumptions

❌ “The payload format seems about right”
✅ “Double checked the API documentation and the payload format is correct.”

2. Assuming Tests Are Sufficient

❌ “A simple smoketest passes”
✅ “Changes to both features pass our tests using real data”

3. Allowing unknowns

❌ “The implemented logic seems not well defined, but let’s merge it first”
✅ “We’ll need to wait to confirm the proper logic before merging”

Remember: A good code review aims to drive the code to be concrete and well tested.