API Backward Compatibility Testing: Preventing Breaking Changes in Microservices

# Install
npm install -g openapi-diff

<span class="hljs-comment"># Compare two specs
openapi-diff old-api.yaml new-api.yaml

<span class="hljs-comment"># JSON output for CI parsing
openapi-diff old-api.yaml new-api.yaml --json > diff-report.json

<span class="hljs-comment"># Exit with non-zero if breaking changes found
openapi-diff old-api.yaml new-api.yaml --fail-on-incompatible

Changes between old-api.yaml and new-api.yaml:

INCOMPATIBLE changes:
  - [REQUEST_BODY_REQUIRED_PROPERTY_ADDED] POST /users: required property 'phone' added
  - [RESPONSE_PROPERTY_REMOVED] GET /users/{id}: response property 'address' removed

COMPATIBLE changes:
  - [RESPONSE_OPTIONAL_PROPERTY_ADDED] GET /users/{id}: optional property 'metadata' added

# Install
npm install -g @useoptic/optic

<span class="hljs-comment"># Add to your repo
optic init

<span class="hljs-comment"># Check for breaking changes against a baseline
optic diff openapi.yaml --base main --check

const { PactV3, MatchersV3 } = require('@pact-foundation/pact');
const { like, eachLike } = MatchersV3;

const provider = new PactV3({
  consumer: 'OrderService',
  provider: 'UserService',
  dir: path.resolve(process.cwd(), 'pacts'),
});

describe('UserService contract', () => {
  it('returns user details for a valid ID', async () => {
    await provider
      .given('user 123 exists')
      .uponReceiving('a request for user 123')
      .withRequest({
        method: 'GET',
        path: '/users/123',
        headers: { Accept: 'application/json' },
      })
      .willRespondWith({
        status: 200,
        headers: { 'Content-Type': 'application/json' },
        body: like({
          id: 123,
          email: 'user@example.com',
          name: 'Alice Smith',
          // NOTE: we depend on 'name' — removing it is a breaking change for us
        }),
      })
      .executeTest(async (mockServer) => {
        const client = new UserServiceClient(mockServer.url);
        const user = await client.getUser(123);
        expect(user.name).toBe('Alice Smith');
      });
  });
});

// Provider verification (runs in UserService CI)
const { Verifier } = require('@pact-foundation/pact');

new Verifier({
  provider: 'UserService',
  providerBaseUrl: 'http://localhost:3000',
  pactBrokerUrl: 'https://your-pact-broker.example.com',
  publishVerificationResult: true,
  providerVersion: process.env.GIT_SHA,
}).verifyProvider();

# .github/workflows/api-compat.yml
name: API Compatibility Check

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'src/**'

jobs:
  openapi-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get baseline spec from main
        run: git show origin/main:openapi.yaml > old-api.yaml

      - name: Install openapi-diff
        run: npm install -g openapi-diff

      - name: Check for breaking changes
        run: openapi-diff old-api.yaml openapi.yaml --fail-on-incompatible

  pact-verification:
    runs-on: ubuntu-latest
    services:
      app:
        image: your-registry/user-service:${{ github.sha }}
        ports:
          - 3000:3000
    steps:
      - uses: actions/checkout@v4

      - name: Verify Pact contracts
        run: |
          npx pact-broker can-i-deploy \
            --pacticipant UserService \
            --version ${{ github.sha }} \
            --to-environment production \
            --broker-base-url ${{ secrets.PACT_BROKER_URL }}
        env:
          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}

# Before
components:
  schemas:
    User:
      required: [id, email]
      properties:
        id:
          type: integer
        email:
          type: string

# After — adding 'phone' as optional (non-breaking)
components:
  schemas:
    User:
      required: [id, email]
      properties:
        id:
          type: integer
        email:
          type: string
        phone:
          type: string
          description: "Optional phone number, may be null"

paths:
  /users/{id}/address:
    get:
      deprecated: true
      description: >
        Deprecated as of 2025-01-01. Use /users/{id} which now includes
        the address object inline. Will be removed in v3 (scheduled 2026-01-01).

app.get('/users/:id/address', (req, res) => {
  res.set('Deprecation', 'true');
  res.set('Sunset', 'Sat, 01 Jan 2026 00:00:00 GMT');
  res.set('Link', '</users/{id}>; rel="successor-version"');
  // ... return response
});

# test_api_compatibility.py
import pytest
import jsonschema
import requests

# Load the v1 schema (your "contract" to consumers)
V1_USER_SCHEMA = {
    "type": "object",
    "required": ["id", "email", "name", "created_at"],
    "properties": {
        "id": {"type": "integer"},
        "email": {"type": "string", "format": "email"},
        "name": {"type": "string"},
        "created_at": {"type": "string", "format": "date-time"},
    },
    "additionalProperties": True,  # Allow new fields (non-breaking additions)
}

def test_user_response_schema_backward_compatible():
    """Verify the current API response satisfies the v1 contract."""
    response = requests.get("http://localhost:3000/users/1",
                            headers={"Authorization": "Bearer test-token"})
    assert response.status_code == 200
    
    # Validate against the minimum required schema
    jsonschema.validate(response.json(), V1_USER_SCHEMA)


def test_required_fields_not_added_to_request():
    """POST /users should still work with only the original required fields."""
    minimal_payload = {
        "email": "newuser@example.com",
        "name": "New User",
        # NOTE: do not add 'phone' here — this tests that phone is truly optional
    }
    response = requests.post("http://localhost:3000/users",
                             json=minimal_payload,
                             headers={"Authorization": "Bearer test-token"})
    assert response.status_code == 201, \
        f"Adding required fields to POST /users is a breaking change: {response.text}"


def test_enum_values_not_removed():
    """All v1 status enum values must still be accepted."""
    v1_status_values = ["active", "inactive", "pending"]
    for status in v1_status_values:
        response = requests.get(f"http://localhost:3000/users?status={status}",
                                headers={"Authorization": "Bearer test-token"})
        assert response.status_code != 400, \
            f"status={status} was a valid v1 enum value but now returns 400 — breaking change"