Contract-first (or design-first) means you define the API contract (URLs, request/response shapes, errors) before writing server or client code. The contract is the source of truth. You can generate server stubs, client SDKs, documentation, and mocks from it. When the contract changes, you regenerate and fix code—everyone stays aligned.

The alternative is code-first: you build the API and then generate a spec from the code. That works but often the spec lags or differs from behavior. Contract-first forces you to think about the API surface first.

OpenAPI (formerly Swagger) is a YAML/JSON format for REST APIs. You describe paths, methods, parameters, request/response schemas, and status codes. Tools like Swagger UI render interactive docs; openapi-generator or Stoplight generate clients and server skeletons in many languages.

Write the spec by hand or with an editor (e.g. Stoplight, Redoc). Use $ref to reuse schemas. Validate the spec with swagger-cli validate. Integrate into CI so breaking changes are caught before merge.

Protocol Buffers (Protobuf) define message and service types in .proto files. gRPC uses Protobuf for RPC: you define a service with rpc methods and request/response messages. The compiler (protoc) generates client and server code. Binary encoding and HTTP/2 make gRPC fast and efficient for service-to-service calls.

Contract-first here means: edit .proto, run protoc, then implement the generated interfaces. Version by adding new fields or new RPCs; avoid removing or changing existing ones to stay backward compatible.

Typical flow: (1) Write or update the contract. (2) Generate server stubs and implement handlers. (3) Generate client SDK and use in consumers. (4) Run contract tests (e.g. Pact, or tests that hit the spec) in CI. When someone changes the contract, CI fails for consumers until they update.

Benefits: documentation is always current; clients get type-safe SDKs; breaking changes are visible in the diff; mocking is easy (implement the contract).