Communication: Sync, Async and Contracts

How services talk

Synchronous communication (REST over HTTP, gRPC with Protocol Buffers, GraphQL at the edge) suits queries and commands where the caller needs an answer now; it is simple to reason about but creates temporal coupling: if the callee is down, the caller fails. Asynchronous communication (message queues, event streams) decouples services in time and suits notifications, propagation of facts and long-running work, at the cost of eventual consistency and harder debugging. Most systems use both: sync for reads and user-facing decisions, async for side effects and data propagation. Either way, the contract (API schema or event schema) is what lets teams deploy independently, so treat it seriously: document it with OpenAPI, protobuf files or AsyncAPI; make changes backward compatible (add optional fields, never rename or remove without a deprecation period); version breaking changes; and verify with consumer-driven contract tests.

A backward-compatible API change

New clients use the new field; old clients keep working because nothing was removed.

# OpenAPI excerpt for GET /orders/{id}
components:
  schemas:
    Order:
      type: object
      required: [id, status, totalMinor, currency]
      properties:
        id:          { type: string }
        status:      { type: string, enum: [PLACED, PAID, SHIPPED, CANCELLED] }
        totalMinor:  { type: integer }
        currency:    { type: string }
        # added in v1.4 - optional, so existing clients are unaffected
        estimatedDelivery:
          type: string
          format: date
# breaking changes (rename, remove, change type) -> new version (/v2) + deprecation period

Adding enum values can break clients

A client with a strict switch over status may crash on a new value such as RETURNED. Document that clients must tolerate unknown enum values, and test for it.

त्वरित जाँच: Which change to a public API response is usually backward compatible?

• Adding a new optional field
• Renaming a required field
• Removing a field clients use
• Changing a field from integer to string