Contract Testing & API Compatibility

Breaking Change Detection

What Constitutes a Breaking Change

Pre-Merge Compatibility Check

Before merging any API change:

1. Diff response types — Compare before/after TypeScript types or JSON schemas
2. Check all consumers — grep for endpoint usage across services and client apps
3. Run contract tests — verify existing consumers still work with new response shape
4. Check generated clients — if using OpenAPI codegen, regenerate and check for compile errors

Response Shape Validation

// Define the contract as a schema
const UserResponseSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string(),
  createdAt: z.string().datetime(),
  // Optional fields can be added without breaking
  avatar: z.string().url().optional(),
});

// Validate in integration tests
test('GET /users/:id returns valid response shape', async () => {
  const response = await api.get('/users/test-id');
  const result = UserResponseSchema.safeParse(response.data);
  expect(result.success).toBe(true);
});

Deprecation Workflow

Timeline

Week 0:  Add deprecation header + docs
         Deprecation: @{DEPRECATION_UNIX_SECONDS}
         Sunset: {SUNSET_HTTP_DATE}

Week 1-4: Monitor usage of deprecated endpoint/field
          Log warnings when deprecated features are accessed

Week 4:  Contact remaining consumers directly

Week 8:  Remove deprecated feature (or extend if consumers remain)

Deprecation Header Pattern

// Add to deprecated endpoints
// RFC 9745: Deprecation is a structured-field Date (@ + Unix seconds).
// RFC 8594: Sunset is an HTTP-date and must not be earlier than Deprecation.
res.setHeader('Deprecation', '@{DEPRECATION_UNIX_SECONDS}');
res.setHeader('Sunset', '{SUNSET_HTTP_DATE}'); // e.g. 'Wed, 30 Jun 2027 23:59:59 GMT'
res.setHeader('Link', '</api/v2/users>; rel="successor-version"');

Consumer-Driven Contract Testing

Provider Side (API)

// Contract test: verify the API still satisfies consumer expectations
describe('User API Contract', () => {
  it('returns fields that Consumer A depends on', async () => {
    const response = await request(app).get('/api/users/1');
    // Consumer A uses: id, email, name
    expect(response.body).toHaveProperty('id');
    expect(response.body).toHaveProperty('email');
    expect(response.body).toHaveProperty('name');
    expect(typeof response.body.id).toBe('string');
    expect(typeof response.body.email).toBe('string');
  });
});

Consumer Side (Client)

// Contract test: verify the client handles the expected response shape
describe('User API Client Contract', () => {
  it('correctly parses user response', () => {
    const mockResponse = { id: '123', email: 'test@example.com', name: 'Test' };
    const user = parseUserResponse(mockResponse);
    expect(user.id).toBe('123');
  });
});

API Versioning Strategy

Rules

• New fields: always optional (additive changes are safe)
• Removed fields: deprecate with sunset date, never remove without warning
• Type changes: add new field, never change existing field type
• Every breaking change must bump the API version
• Contract tests run in CI — failures block merge