System Design (HLD)Inter-Service Communication

Inter-Service Communication

LevelAdvanced

Duration90 mins

TopicInter-Service Communication

2 / 5

API Contracts

The Invisible Agreements That Hold Systems Together

In a microservices architecture, services are like independent companies doing business with each other. Just as companies rely on legal contracts to define expectations, services rely on API contracts to define how they communicate. These contracts specify what requests look like, what responses to expect, and what error conditions may occur.

Without explicit, well-maintained contracts, microservices devolve into a fragile web of implicit dependencies. A seemingly innocent change in one service's response format cascades into production failures across dozens of dependent services. Teams become afraid to change anything, and the promised independence of microservices evaporates.

API contracts are not optional—they are the foundation upon which microservices independence is built.

What You Will Master

By the end of this page, you will understand how to design robust API contracts, the different schema languages available, how to validate compatibility between contract versions, and how contract testing enables truly independent service deployment. You'll learn to treat APIs as products and contracts as the specification that enables ecosystem growth.

What is an API Contract?

An API contract is a formal specification that describes the interface between two services. It defines:

Endpoints/Operations: What actions are available
Request Schemas: What data must be sent and in what format
Response Schemas: What data will be returned and in what format
Error Conditions: What error responses are possible and when
Authentication: How callers identify themselves
Rate Limits: Usage constraints and quotas
Behavioral Guarantees: Idempotency, ordering, consistency expectations

The contract serves as the single source of truth for how services interact. It's both documentation and enforcement mechanism.

Contract as Product Interface

Think of your API contract as the user interface for developers. Just as a well-designed UI makes software easy to use, a well-designed contract makes services easy to integrate. The contract is often the first thing consumers see—it shapes their impression of your service and determines how quickly they can integrate.

Implicit vs Explicit Contracts

Implicit contracts emerge naturally when services communicate:

"The order service returns JSON with these fields..."
"Null values appear when the order is incomplete..."
"Errors come back as HTTP 500 with a message..."

These implicit contracts are dangerous because:

They're not documented—consumers discover them through trial and error
They're not versioned—changes happen silently
They're not validated—incompatibilities surface only in production
They're not discoverable—new consumers must reverse-engineer behavior

Explicit contracts are formal specifications:

Written in a schema language (OpenAPI, Protocol Buffers, JSON Schema, etc.)
Versioned alongside the service code
Validated at build time and in CI pipelines
Published for consumers to discover and generate clients from

Implicit vs Explicit Contracts Comparison
Aspect	Implicit Contract	Explicit Contract
Documentation	Tribal knowledge or outdated docs	Schema is the documentation (always current)
Discoverability	Read source code or ask the team	Published schema, auto-generated docs
Validation	Runtime errors in production	Compile-time errors, CI failures
Client Generation	Manual HTTP calls	Auto-generated type-safe clients
Breaking Changes	Discovered by angry consumers	Detected by compatibility checks
Evolution	Fear of changing anything	Confident evolution with versioning

Schema Languages and Formats

Several schema languages have emerged for defining API contracts. Each has strengths suited to different contexts.

OpenAPI (formerly Swagger)

The dominant standard for REST APIs. OpenAPI specifications are YAML or JSON documents describing HTTP endpoints, request/response schemas, authentication, and more.

Strengths:

Universal tooling ecosystem (editors, validators, code generators)
Human-readable YAML format
Rich documentation generation (Swagger UI, Redoc)
Supported by virtually all API gateways

Weaknesses:

Verbose for complex schemas
No built-in code generation (relies on external tools)
HTTP-specific (doesn't apply to messaging systems)

Protocol Buffers (Protobuf)

Google's language-neutral, platform-neutral serialization format. Used primarily with gRPC but applicable beyond.

Strengths:

Extremely compact binary format (3-10x smaller than JSON)
Built-in code generation for multiple languages
Strong typing with backward/forward compatibility rules
Excellent for high-performance, high-volume APIs

Weaknesses:

Binary format not human-readable
Learning curve for .proto syntax
Tooling less ubiquitous than OpenAPI

JSON Schema

A vocabulary for annotating and validating JSON documents. Often used within OpenAPI but can stand alone.

Strengths:

JSON-native (works with any JSON-based API)
Composable and reusable schemas
Rich validation capabilities (patterns, ranges, dependencies)

Weaknesses:

No endpoint/operation definition (just data shapes)
Verbose for complex schemas
Version fragmentation (Draft-04, Draft-07, Draft 2020-12)

AsyncAPI

OpenAPI's equivalent for asynchronous, event-driven APIs. Describes message brokers, topics, and event schemas.

Strengths:

Purpose-built for event-driven architectures
Supports multiple protocols (Kafka, AMQP, WebSocket, etc.)
Similar syntax to OpenAPI (easy transition)

Weaknesses:

Younger ecosystem, less tooling
Complex for simple pub-sub scenarios

contract-examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
# OpenAPI 3.1 Specification Example
openapi: 3.1.0
info:
  title: Order Service API
  version: 2.3.0
  description: |
    API for managing customer orders. Supports order creation,
    retrieval, and status updates.
  
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create a new order
      tags: [Orders]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '409':
          description: Duplicate order (idempotency key conflict)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
 
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve order by ID
      tags: [Orders]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Order found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
 
components:
  schemas:
    CreateOrderRequest:
      type: object
      required: [customerId, items, idempotencyKey]
      properties:
        customerId:
          type: string
          format: uuid
          description: The customer placing the order
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItem'
        idempotencyKey:
          type: string
          description: Client-generated key for deduplication
          x-example: "order-2024-01-08-abc123"
        
    OrderItem:
      type: object
      required: [productId, quantity]
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
          maximum: 100
        notes:
          type: string
          maxLength: 500
          
    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        status:
          type: string
          enum: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
        totalAmount:
          type: number
          format: decimal
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

Contract Design Principles

Well-designed contracts share common principles that ensure usability, maintainability, and evolvability.

Core Contract Design Principles

•Be Explicit About Everything — Never rely on implicit behavior. Document nullability, optionality, default values, and edge cases. What happens when a list is empty? What does null mean versus absent?
•Design for the Consumer — The contract exists for consumers, not providers. Optimize for ease of integration. Group related operations. Use consistent naming. Provide examples.
•Plan for Evolution — Every contract will change. Use versioning from day one. Design fields with explicit optionality. Reserve field numbers (in protobuf) for future use.
•Make Illegal States Unrepresentable — If an order must have at least one item, the schema should enforce it (minItems: 1). If quantity can't be negative, specify minimum: 1. Push validation into the contract.
•Include Metadata — Every response should include information for debugging and tracing: request ID, timestamp, pagination info, rate limit headers. This isn't noise—it's essential operational data.
•Error Contracts Matter — Errors are part of the contract. Define error response schemas with codes, messages, and field-level details. Consumers need to handle errors programmatically.

The Postel's Law Trap

"Be conservative in what you send, be liberal in what you accept" sounds wise but leads to problems. Liberal acceptance creates implicit contracts—consumers depend on lenient parsing. When you later enforce stricter parsing, you break those consumers. Instead: be strict in both sending AND receiving, but use explicit versioning to evolve without breaking.

Naming Conventions

Consistent naming dramatically improves contract usability:

Field Names:

Use camelCase or snake_case consistently (never mix)
Prefer verbose clarity over brevity: customerEmailAddress not email
Boolean fields should be obvious questions: isActive, hasShipped, canCancel
IDs should be suffixed: orderId, customerId (not just id)

Endpoint Patterns:

Collections are plural: /orders, /customers
Individual items by ID: /orders/{orderId}
Actions as verbs (sparingly): /orders/{orderId}/cancel
Nested when ownership is clear: /customers/{customerId}/orders

Enum Values:

Use SCREAMING_SNAKE_CASE: ORDER_STATUS_PENDING
Include namespace prefix to avoid collisions
Reserve 0 or first value for "unspecified" state

Common Contract Design Mistakes
Mistake	Problem	Better Approach
Stringly-typed fields	"2024-01-08" vs "01/08/2024" vs "Jan 8, 2024"	Explicit formats: format: date-time (ISO 8601)
Ambiguous nullability	Does [] mean empty list or unknown?	Separate null (unknown) from [] (known empty)
Generic error responses	{"error": "Something went wrong"}	Structured errors with codes, fields affected
Exposing internal IDs	Database autoincrement IDs leak info	UUIDs or opaque identifiers
Inconsistent casing	userId vs user_id vs UserID	Pick one convention, enforce via linting
No pagination	Return all 10,000 results	Cursor-based or offset pagination from start

Backward and Forward Compatibility

The ability to evolve contracts without breaking consumers is fundamental to microservices independence. This requires understanding compatibility rules.

Backward Compatibility

A change is backward compatible if existing consumers continue to work without modification. The provider can be upgraded without requiring consumer updates.

Backward-Compatible Changes:

Adding new optional fields to responses
Adding new optional parameters to requests
Adding new endpoints or operations
Adding new enum values (if consumers ignore unknown values)
Relaxing validation constraints (making required fields optional)

Breaking Changes (NOT Backward Compatible):

Removing fields from responses
Adding required fields to requests
Renaming fields
Changing field types
Changing field semantics (same name, different meaning)
Removing endpoints or operations
Tightening validation constraints

Forward Compatibility

A change is forward compatible if new consumers can work with old providers. This is less common but important for gradual rollouts.

Forward-Compatible Changes:

Adding optional fields that old providers ignore
Consumers tolerating missing optional fields
Consumers ignoring unknown fields in responses

Safe Contract Changes

•Add optional response fields
•Add optional request parameters
•Add new endpoints
•Add new enum values (with consumer tolerance)
•Make required fields optional
•Extend string length limits
•Broaden numeric ranges

Breaking Contract Changes

•Remove response fields
•Add required request fields
•Rename fields
•Change field types
•Change field semantics
•Remove endpoints
•Tighten validation rules

The Golden Rule of Contract Evolution

Always add new things as optional. Never remove things without a deprecation period. Never change the meaning of existing things. When in doubt, create a new version of the API.

compatibility-checking
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Using buf for protobuf compatibility checking
# buf.yaml configuration
version: v1
breaking:
  use:
    - FILE  # Check breaking changes at file level
rules:
  # Common breaking change rules
  - FIELD_NO_DELETE
  - FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED
  - FIELD_SAME_TYPE
  - FIELD_SAME_NAME
  - REQUIRED_FIELD_NO_DELETE
  - ENUM_VALUE_NO_DELETE
  - RPC_NO_DELETE
  - SERVICE_NO_DELETE
 
# Run compatibility check against previous version
buf breaking --against git#branch=main
 
# Output example when breaking change detected:
# order_service.proto:45:3: Field "15" on message "Order" changed type 
# from "string" to "int64".

Contract Testing

Contract testing verifies that services correctly implement their contracts without requiring end-to-end integration tests. It's the mechanism that enables independent deployment with confidence.

The Problem Contract Testing Solves

In a microservices system:

End-to-end tests are slow, flaky, and expensive
Integration environments are shared and contentious
Waiting for all services to be deployed together defeats the purpose
Without testing, you discover contract violations in production

Contract testing solves this by:

Testing contracts in isolation (fast, reliable)
Running in CI before merge (shift left)
Detecting breaking changes before deployment
Enabling truly independent releases

Contract Testing Approaches

Provider-Side Testing (Schema Validation) The provider tests that its actual responses match its published contract.

Contract Schema → Generate Mock Requests → Hit Real Provider → Validate Against Schema

Consumer-Side Testing (Pact-style) Consumers declare their expectations (what they need from providers). Providers verify those expectations.

1. Consumer writes tests recording expectations
2. Expectations published to "Pact Broker"
3. Provider downloads consumer expectations
4. Provider verifies it can fulfill all expectations

Bi-Directional Contract Testing Combining both: provider publishes schema, consumer publishes expectations, broker verifies compatibility between them.

Contract Testing Approaches Comparison
Approach	Who Writes Tests	What's Validated	Tooling Examples
Provider Schema Testing	Provider team	Responses match published schema	OpenAPI validators, Prism, Dredd
Consumer Contract Testing	Consumer team	Provider fulfills consumer expectations	Pact, Spring Cloud Contract
Bi-Directional	Both teams	Schema ↔ expectations compatibility	Pact + schema comparison
Schema Registry	Both teams	Message schemas compatible	Confluent Schema Registry, AWS Glue

contract-testing-example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
// Consumer-side contract test
import { PactV3, MatchersV3 } from '@pact-foundation/pact';
 
const { like, eachLike, string, integer, uuid } = MatchersV3;
 
describe('Order Service Contract', () => {
  const provider = new PactV3({
    consumer: 'PaymentService',
    provider: 'OrderService',
    logLevel: 'warn',
  });
 
  describe('when a valid order exists', () => {
    it('should return the order details', async () => {
      // Define the expected interaction
      await provider
        .given('an order with ID abc-123 exists')
        .uponReceiving('a request to get order abc-123')
        .withRequest({
          method: 'GET',
          path: '/orders/abc-123',
          headers: {
            Accept: 'application/json',
          },
        })
        .willRespondWith({
          status: 200,
          headers: {
            'Content-Type': 'application/json',
          },
          body: {
            // Define what we (the consumer) actually need
            // Not everything the provider returns - just what we use
            id: uuid('abc-123'),
            customerId: uuid(),
            totalAmount: integer(9999),
            status: string('CONFIRMED'),
            items: eachLike({
              productId: uuid(),
              quantity: integer(1),
            }),
          },
        });
 
      // Execute the test
      await provider.executeTest(async (mockServer) => {
        const orderClient = new OrderClient(mockServer.url);
        const order = await orderClient.getOrder('abc-123');
        
        // Verify our code handles the response correctly
        expect(order.id).toBe('abc-123');
        expect(order.totalAmount).toBeGreaterThan(0);
        expect(order.items.length).toBeGreaterThan(0);
      });
    });
  });
 
  describe('when order does not exist', () => {
    it('should return 404', async () => {
      await provider
        .given('no order with ID nonexistent exists')
        .uponReceiving('a request for nonexistent order')
        .withRequest({
          method: 'GET',
          path: '/orders/nonexistent',
        })
        .willRespondWith({
          status: 404,
          body: {
            error: string('ORDER_NOT_FOUND'),
            message: string('Order not found'),
          },
        });
 
      await provider.executeTest(async (mockServer) => {
        const orderClient = new OrderClient(mockServer.url);
        await expect(orderClient.getOrder('nonexistent'))
          .rejects.toThrow('Order not found');
      });
    });
  });
});

Consumer-Driven Contracts

Pact pioneered 'consumer-driven contracts'—consumers declare what they need, and providers must satisfy those needs. This inverts the typical relationship: instead of providers dictating what's available, consumers drive the contract to include only what's actually used. This reveals unused fields and enables confident deprecation.

API Contract Lifecycle Management

Managing contracts is an ongoing discipline, not a one-time design activity. Mature organizations treat contracts as first-class artifacts with defined lifecycle stages.

Contract Lifecycle Stages

1. Design Phase

Draft schema with stakeholder input
Review for naming consistency, completeness
Validate against design principles
Prototype with mock implementations

2. Publication Phase

Version the contract (semver or date-based)
Publish to contract registry/catalog
Generate documentation automatically
Make client SDKs available

3. Active Phase

Monitor usage patterns (which endpoints, which consumers)
Track compatibility across versions
Handle support requests and clarifications
Plan non-breaking enhancements

4. Deprecation Phase

Announce deprecation with timeline
Add deprecation markers to schema
Provide migration guides
Monitor remaining usage
Extend deadline if consumers struggle

5. Retirement Phase

Remove deprecated version
Archive documentation
Clean up associated resources
Post-mortem on migration experience

Contract Governance Best Practices

•Centralized Registry — All contracts published to a single, discoverable location. Teams can browse available APIs, see compatibility status, and auto-generate clients.
•Automated Compatibility Checks — Every PR that modifies a contract runs compatibility checks. Breaking changes block merge until reviewed and approved.
•Deprecation Policy — Minimum notice period before removing anything (e.g., 6 months). Deprecated fields/endpoints clearly marked in schema and documentation.
•Consumer Tracking — Know who consumes your API. Emit usage metrics by consumer. Reach out proactively about deprecations.
•Change Review Process — Significant contract changes go through design review. Involve affected consumers in major changes.

deprecation-example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# Deprecation in OpenAPI
paths:
  /orders/{orderId}/status:
    put:
      operationId: updateOrderStatus
      deprecated: true  # Marks endpoint as deprecated
      x-deprecated-since: "2024-01-08"
      x-sunset-date: "2024-07-08"
      x-replacement: updateOrder
      summary: Update order status (DEPRECATED)
      description: |
        **DEPRECATED**: This endpoint will be removed on 2024-07-08.
        Use PATCH /orders/{orderId} instead with status field in body.
        
        Migration guide: https://docs.company.com/migrations/order-status
 
components:
  schemas:
    Order:
      type: object
      properties:
        # Deprecated field - still returned but will be removed
        legacyCustomerId:
          type: string
          deprecated: true
          description: |
            DEPRECATED: Use 'customerId' (UUID format) instead.
            Will be removed after 2024-06-01.
        
        # New preferred field
        customerId:
          type: string
          format: uuid
          description: Unique customer identifier

Summary: Contracts as the Foundation of Independence

API contracts are the invisible infrastructure that enables microservices to operate as truly independent units. Without explicit contracts, you have a distributed monolith—tightly coupled services that must be deployed together and tested together.

Let's consolidate the key insights:

Key Takeaways

•Explicit contracts are mandatory — Implicit contracts lead to production surprises. Define schemas formally using OpenAPI, Protocol Buffers, or AsyncAPI.
•Design contracts for consumers — The contract is the API's user interface. Optimize for discoverability, consistency, and ease of integration.
•Compatibility enables independence — Backward-compatible changes let providers evolve without breaking consumers. This is the core enabler of independent deployment.
•Contract testing validates compatibility — Use schema validation and consumer-driven contract testing to catch breaking changes before they reach production.
•Versioning is non-negotiable — From day one, version your APIs. Use semantic versioning or date-based versions. Never make breaking changes without a new version.
•Treat deprecation as a process — Announce, mark, monitor, extend, then remove. Respect your consumers' migration timelines.

What's next:

Now that we understand how to define contracts, we'll explore the protocols that carry those contracts across the wire. Protocol selection—REST vs gRPC vs GraphQL vs message queues—determines performance characteristics, streaming capabilities, and operational complexity.

Page Complete

You now understand how to design, validate, test, and evolve API contracts. You can choose appropriate schema languages, implement contract testing, and manage the contract lifecycle. Next, we'll dive into protocol selection—choosing the right transport mechanism for different communication needs.

2 / 5

Loading learning content...

System Design (HLD)Inter-Service Communication

Inter-Service Communication

LevelAdvanced

Duration90 mins

TopicInter-Service Communication

2 / 5

API Contracts

The Invisible Agreements That Hold Systems Together

API contracts are not optional—they are the foundation upon which microservices independence is built.

What You Will Master

What is an API Contract?

An API contract is a formal specification that describes the interface between two services. It defines:

Endpoints/Operations: What actions are available
Request Schemas: What data must be sent and in what format
Response Schemas: What data will be returned and in what format
Error Conditions: What error responses are possible and when
Authentication: How callers identify themselves
Rate Limits: Usage constraints and quotas
Behavioral Guarantees: Idempotency, ordering, consistency expectations

The contract serves as the single source of truth for how services interact. It's both documentation and enforcement mechanism.

Contract as Product Interface

Implicit vs Explicit Contracts

Implicit contracts emerge naturally when services communicate:

"The order service returns JSON with these fields..."
"Null values appear when the order is incomplete..."
"Errors come back as HTTP 500 with a message..."

These implicit contracts are dangerous because:

They're not documented—consumers discover them through trial and error
They're not versioned—changes happen silently
They're not validated—incompatibilities surface only in production
They're not discoverable—new consumers must reverse-engineer behavior

Explicit contracts are formal specifications:

Written in a schema language (OpenAPI, Protocol Buffers, JSON Schema, etc.)
Versioned alongside the service code
Validated at build time and in CI pipelines
Published for consumers to discover and generate clients from

Implicit vs Explicit Contracts Comparison
Aspect	Implicit Contract	Explicit Contract
Documentation	Tribal knowledge or outdated docs	Schema is the documentation (always current)
Discoverability	Read source code or ask the team	Published schema, auto-generated docs
Validation	Runtime errors in production	Compile-time errors, CI failures
Client Generation	Manual HTTP calls	Auto-generated type-safe clients
Breaking Changes	Discovered by angry consumers	Detected by compatibility checks
Evolution	Fear of changing anything	Confident evolution with versioning

Schema Languages and Formats

Several schema languages have emerged for defining API contracts. Each has strengths suited to different contexts.

OpenAPI (formerly Swagger)

The dominant standard for REST APIs. OpenAPI specifications are YAML or JSON documents describing HTTP endpoints, request/response schemas, authentication, and more.

Strengths:

Universal tooling ecosystem (editors, validators, code generators)
Human-readable YAML format
Rich documentation generation (Swagger UI, Redoc)
Supported by virtually all API gateways

Weaknesses:

Verbose for complex schemas
No built-in code generation (relies on external tools)
HTTP-specific (doesn't apply to messaging systems)

Protocol Buffers (Protobuf)

Google's language-neutral, platform-neutral serialization format. Used primarily with gRPC but applicable beyond.

Strengths:

Extremely compact binary format (3-10x smaller than JSON)
Built-in code generation for multiple languages
Strong typing with backward/forward compatibility rules
Excellent for high-performance, high-volume APIs

Weaknesses:

Binary format not human-readable
Learning curve for .proto syntax
Tooling less ubiquitous than OpenAPI

JSON Schema

A vocabulary for annotating and validating JSON documents. Often used within OpenAPI but can stand alone.

Strengths:

JSON-native (works with any JSON-based API)
Composable and reusable schemas
Rich validation capabilities (patterns, ranges, dependencies)

Weaknesses:

No endpoint/operation definition (just data shapes)
Verbose for complex schemas
Version fragmentation (Draft-04, Draft-07, Draft 2020-12)

AsyncAPI

OpenAPI's equivalent for asynchronous, event-driven APIs. Describes message brokers, topics, and event schemas.

Strengths:

Purpose-built for event-driven architectures
Supports multiple protocols (Kafka, AMQP, WebSocket, etc.)
Similar syntax to OpenAPI (easy transition)

Weaknesses:

Younger ecosystem, less tooling
Complex for simple pub-sub scenarios

contract-examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
# OpenAPI 3.1 Specification Example
openapi: 3.1.0
info:
  title: Order Service API
  version: 2.3.0
  description: |
    API for managing customer orders. Supports order creation,
    retrieval, and status updates.
  
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create a new order
      tags: [Orders]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '409':
          description: Duplicate order (idempotency key conflict)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
 
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve order by ID
      tags: [Orders]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Order found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
 
components:
  schemas:
    CreateOrderRequest:
      type: object
      required: [customerId, items, idempotencyKey]
      properties:
        customerId:
          type: string
          format: uuid
          description: The customer placing the order
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItem'
        idempotencyKey:
          type: string
          description: Client-generated key for deduplication
          x-example: "order-2024-01-08-abc123"
        
    OrderItem:
      type: object
      required: [productId, quantity]
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
          maximum: 100
        notes:
          type: string
          maxLength: 500
          
    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        status:
          type: string
          enum: [PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
        totalAmount:
          type: number
          format: decimal
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

Contract Design Principles

Well-designed contracts share common principles that ensure usability, maintainability, and evolvability.

Core Contract Design Principles

•Be Explicit About Everything — Never rely on implicit behavior. Document nullability, optionality, default values, and edge cases. What happens when a list is empty? What does null mean versus absent?
•Design for the Consumer — The contract exists for consumers, not providers. Optimize for ease of integration. Group related operations. Use consistent naming. Provide examples.
•Plan for Evolution — Every contract will change. Use versioning from day one. Design fields with explicit optionality. Reserve field numbers (in protobuf) for future use.
•Make Illegal States Unrepresentable — If an order must have at least one item, the schema should enforce it (minItems: 1). If quantity can't be negative, specify minimum: 1. Push validation into the contract.
•Include Metadata — Every response should include information for debugging and tracing: request ID, timestamp, pagination info, rate limit headers. This isn't noise—it's essential operational data.
•Error Contracts Matter — Errors are part of the contract. Define error response schemas with codes, messages, and field-level details. Consumers need to handle errors programmatically.

The Postel's Law Trap

Naming Conventions

Consistent naming dramatically improves contract usability:

Field Names:

Use camelCase or snake_case consistently (never mix)
Prefer verbose clarity over brevity: customerEmailAddress not email
Boolean fields should be obvious questions: isActive, hasShipped, canCancel
IDs should be suffixed: orderId, customerId (not just id)

Endpoint Patterns:

Collections are plural: /orders, /customers
Individual items by ID: /orders/{orderId}
Actions as verbs (sparingly): /orders/{orderId}/cancel
Nested when ownership is clear: /customers/{customerId}/orders

Enum Values:

Use SCREAMING_SNAKE_CASE: ORDER_STATUS_PENDING
Include namespace prefix to avoid collisions
Reserve 0 or first value for "unspecified" state

Common Contract Design Mistakes
Mistake	Problem	Better Approach
Stringly-typed fields	"2024-01-08" vs "01/08/2024" vs "Jan 8, 2024"	Explicit formats: format: date-time (ISO 8601)
Ambiguous nullability	Does [] mean empty list or unknown?	Separate null (unknown) from [] (known empty)
Generic error responses	{"error": "Something went wrong"}	Structured errors with codes, fields affected
Exposing internal IDs	Database autoincrement IDs leak info	UUIDs or opaque identifiers
Inconsistent casing	userId vs user_id vs UserID	Pick one convention, enforce via linting
No pagination	Return all 10,000 results	Cursor-based or offset pagination from start

Backward and Forward Compatibility

The ability to evolve contracts without breaking consumers is fundamental to microservices independence. This requires understanding compatibility rules.

Backward Compatibility

A change is backward compatible if existing consumers continue to work without modification. The provider can be upgraded without requiring consumer updates.

Backward-Compatible Changes:

Adding new optional fields to responses
Adding new optional parameters to requests
Adding new endpoints or operations
Adding new enum values (if consumers ignore unknown values)
Relaxing validation constraints (making required fields optional)

Breaking Changes (NOT Backward Compatible):

Removing fields from responses
Adding required fields to requests
Renaming fields
Changing field types
Changing field semantics (same name, different meaning)
Removing endpoints or operations
Tightening validation constraints

Forward Compatibility

A change is forward compatible if new consumers can work with old providers. This is less common but important for gradual rollouts.

Forward-Compatible Changes:

Adding optional fields that old providers ignore
Consumers tolerating missing optional fields
Consumers ignoring unknown fields in responses

Safe Contract Changes

•Add optional response fields
•Add optional request parameters
•Add new endpoints
•Add new enum values (with consumer tolerance)
•Make required fields optional
•Extend string length limits
•Broaden numeric ranges

Breaking Contract Changes

•Remove response fields
•Add required request fields
•Rename fields
•Change field types
•Change field semantics
•Remove endpoints
•Tighten validation rules

The Golden Rule of Contract Evolution

Always add new things as optional. Never remove things without a deprecation period. Never change the meaning of existing things. When in doubt, create a new version of the API.

compatibility-checking
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Using buf for protobuf compatibility checking
# buf.yaml configuration
version: v1
breaking:
  use:
    - FILE  # Check breaking changes at file level
rules:
  # Common breaking change rules
  - FIELD_NO_DELETE
  - FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED
  - FIELD_SAME_TYPE
  - FIELD_SAME_NAME
  - REQUIRED_FIELD_NO_DELETE
  - ENUM_VALUE_NO_DELETE
  - RPC_NO_DELETE
  - SERVICE_NO_DELETE
 
# Run compatibility check against previous version
buf breaking --against git#branch=main
 
# Output example when breaking change detected:
# order_service.proto:45:3: Field "15" on message "Order" changed type 
# from "string" to "int64".

Contract Testing

Contract testing verifies that services correctly implement their contracts without requiring end-to-end integration tests. It's the mechanism that enables independent deployment with confidence.

The Problem Contract Testing Solves

In a microservices system:

End-to-end tests are slow, flaky, and expensive
Integration environments are shared and contentious
Waiting for all services to be deployed together defeats the purpose
Without testing, you discover contract violations in production

Contract testing solves this by:

Testing contracts in isolation (fast, reliable)
Running in CI before merge (shift left)
Detecting breaking changes before deployment
Enabling truly independent releases

Contract Testing Approaches

Provider-Side Testing (Schema Validation) The provider tests that its actual responses match its published contract.

Contract Schema → Generate Mock Requests → Hit Real Provider → Validate Against Schema

Consumer-Side Testing (Pact-style) Consumers declare their expectations (what they need from providers). Providers verify those expectations.

1. Consumer writes tests recording expectations
2. Expectations published to "Pact Broker"
3. Provider downloads consumer expectations
4. Provider verifies it can fulfill all expectations

Bi-Directional Contract Testing Combining both: provider publishes schema, consumer publishes expectations, broker verifies compatibility between them.

Contract Testing Approaches Comparison
Approach	Who Writes Tests	What's Validated	Tooling Examples
Provider Schema Testing	Provider team	Responses match published schema	OpenAPI validators, Prism, Dredd
Consumer Contract Testing	Consumer team	Provider fulfills consumer expectations	Pact, Spring Cloud Contract
Bi-Directional	Both teams	Schema ↔ expectations compatibility	Pact + schema comparison
Schema Registry	Both teams	Message schemas compatible	Confluent Schema Registry, AWS Glue

contract-testing-example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
// Consumer-side contract test
import { PactV3, MatchersV3 } from '@pact-foundation/pact';
 
const { like, eachLike, string, integer, uuid } = MatchersV3;
 
describe('Order Service Contract', () => {
  const provider = new PactV3({
    consumer: 'PaymentService',
    provider: 'OrderService',
    logLevel: 'warn',
  });
 
  describe('when a valid order exists', () => {
    it('should return the order details', async () => {
      // Define the expected interaction
      await provider
        .given('an order with ID abc-123 exists')
        .uponReceiving('a request to get order abc-123')
        .withRequest({
          method: 'GET',
          path: '/orders/abc-123',
          headers: {
            Accept: 'application/json',
          },
        })
        .willRespondWith({
          status: 200,
          headers: {
            'Content-Type': 'application/json',
          },
          body: {
            // Define what we (the consumer) actually need
            // Not everything the provider returns - just what we use
            id: uuid('abc-123'),
            customerId: uuid(),
            totalAmount: integer(9999),
            status: string('CONFIRMED'),
            items: eachLike({
              productId: uuid(),
              quantity: integer(1),
            }),
          },
        });
 
      // Execute the test
      await provider.executeTest(async (mockServer) => {
        const orderClient = new OrderClient(mockServer.url);
        const order = await orderClient.getOrder('abc-123');
        
        // Verify our code handles the response correctly
        expect(order.id).toBe('abc-123');
        expect(order.totalAmount).toBeGreaterThan(0);
        expect(order.items.length).toBeGreaterThan(0);
      });
    });
  });
 
  describe('when order does not exist', () => {
    it('should return 404', async () => {
      await provider
        .given('no order with ID nonexistent exists')
        .uponReceiving('a request for nonexistent order')
        .withRequest({
          method: 'GET',
          path: '/orders/nonexistent',
        })
        .willRespondWith({
          status: 404,
          body: {
            error: string('ORDER_NOT_FOUND'),
            message: string('Order not found'),
          },
        });
 
      await provider.executeTest(async (mockServer) => {
        const orderClient = new OrderClient(mockServer.url);
        await expect(orderClient.getOrder('nonexistent'))
          .rejects.toThrow('Order not found');
      });
    });
  });
});

Consumer-Driven Contracts

API Contract Lifecycle Management

Managing contracts is an ongoing discipline, not a one-time design activity. Mature organizations treat contracts as first-class artifacts with defined lifecycle stages.

Contract Lifecycle Stages

1. Design Phase

Draft schema with stakeholder input
Review for naming consistency, completeness
Validate against design principles
Prototype with mock implementations

2. Publication Phase

Version the contract (semver or date-based)
Publish to contract registry/catalog
Generate documentation automatically
Make client SDKs available

3. Active Phase

Monitor usage patterns (which endpoints, which consumers)
Track compatibility across versions
Handle support requests and clarifications
Plan non-breaking enhancements

4. Deprecation Phase

Announce deprecation with timeline
Add deprecation markers to schema
Provide migration guides
Monitor remaining usage
Extend deadline if consumers struggle

5. Retirement Phase

Remove deprecated version
Archive documentation
Clean up associated resources
Post-mortem on migration experience

Contract Governance Best Practices

•Centralized Registry — All contracts published to a single, discoverable location. Teams can browse available APIs, see compatibility status, and auto-generate clients.
•Automated Compatibility Checks — Every PR that modifies a contract runs compatibility checks. Breaking changes block merge until reviewed and approved.
•Deprecation Policy — Minimum notice period before removing anything (e.g., 6 months). Deprecated fields/endpoints clearly marked in schema and documentation.
•Consumer Tracking — Know who consumes your API. Emit usage metrics by consumer. Reach out proactively about deprecations.
•Change Review Process — Significant contract changes go through design review. Involve affected consumers in major changes.

deprecation-example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# Deprecation in OpenAPI
paths:
  /orders/{orderId}/status:
    put:
      operationId: updateOrderStatus
      deprecated: true  # Marks endpoint as deprecated
      x-deprecated-since: "2024-01-08"
      x-sunset-date: "2024-07-08"
      x-replacement: updateOrder
      summary: Update order status (DEPRECATED)
      description: |
        **DEPRECATED**: This endpoint will be removed on 2024-07-08.
        Use PATCH /orders/{orderId} instead with status field in body.
        
        Migration guide: https://docs.company.com/migrations/order-status
 
components:
  schemas:
    Order:
      type: object
      properties:
        # Deprecated field - still returned but will be removed
        legacyCustomerId:
          type: string
          deprecated: true
          description: |
            DEPRECATED: Use 'customerId' (UUID format) instead.
            Will be removed after 2024-06-01.
        
        # New preferred field
        customerId:
          type: string
          format: uuid
          description: Unique customer identifier

Summary: Contracts as the Foundation of Independence

Let's consolidate the key insights:

Key Takeaways

•Explicit contracts are mandatory — Implicit contracts lead to production surprises. Define schemas formally using OpenAPI, Protocol Buffers, or AsyncAPI.
•Design contracts for consumers — The contract is the API's user interface. Optimize for discoverability, consistency, and ease of integration.
•Compatibility enables independence — Backward-compatible changes let providers evolve without breaking consumers. This is the core enabler of independent deployment.
•Contract testing validates compatibility — Use schema validation and consumer-driven contract testing to catch breaking changes before they reach production.
•Versioning is non-negotiable — From day one, version your APIs. Use semantic versioning or date-based versions. Never make breaking changes without a new version.
•Treat deprecation as a process — Announce, mark, monitor, extend, then remove. Respect your consumers' migration timelines.

What's next:

Page Complete

2 / 5