Microservice Contracts — Vocabulary and Discussion Language

A service contract defines the public API interface: endpoints, HTTP methods, request schemas, response schemas, error codes, authentication requirements, and rate limits. The consuming service can only depend on what is in the contract — internal implementation can change freely. The owning service is responsible for maintaining the contract.

Breaking change: any API change that existing consumers must update their code to handle. Examples: removing a response field, changing a field type, renaming an endpoint, adding a required request parameter. Non-breaking: adding an optional field, adding a new endpoint, adding values to an enum (with caution). Semantic versioning (major version bump) signals breaking changes.

Consumer-Driven Contracts (Pact, Spring Cloud Contract): each consumer publishes what it expects from the provider (specific request-response pairs). The provider runs all consumer contracts in its test suite to verify it satisfies every consumer. This prevents breaking changes without provider-consumer integration tests — catching breaking changes in CI before they reach production.

Graceful degradation: if Service A depends on Service B, and B is down, A should not fail completely. Instead: return cached data, return partial results with a warning, disable the affected feature, or fall back to defaults. Graceful degradation prevents cascade failures — where one service outage cascades through the system.

Idempotency: POST /orders called once vs. called 3 times (due to retries after network failure) should result in one order, not three. Idempotency is typically implemented with a client-supplied idempotency key: the first request with key X creates the order; subsequent requests with the same key X return the same response without creating duplicate orders.