API and Service Design

APIs are long-lived contracts. Design them for clear ownership, backward compatibility, observability, and safe evolution.

Service boundary checklist

Before creating or changing a service boundary, define:

• Business capability and owning team.
• Consumers and expected traffic patterns.
• Data ownership and source of truth.
• Authentication and authorization model.
• Versioning and deprecation policy.
• SLOs, rate limits, and failure behavior.
• Support channel and escalation path.

API styles

Use the simplest API style that fits the interaction.

• REST for resource-oriented request and response APIs.
• GraphQL when clients need flexible reads across related entities.
• gRPC for internal high-throughput service-to-service calls.
• Events when producers should not block on consumers.
• Files or batch interfaces when the business process is batch-shaped.

Compatibility

Favor additive changes.

• Add fields instead of renaming or removing them.
• Treat enum additions as breaking unless consumers are prepared.
• Version events and APIs when behavior changes materially.
• Document deprecation windows and migration paths.
• Validate contracts in CI for critical consumers.

Operational requirements

Every production API should expose:

• Structured logs with correlation IDs.
• Metrics for latency, traffic, errors, and saturation.
• Traces across downstream dependencies.
• Clear error codes and retry guidance.
• Rate limits, quotas, and abuse controls.
• Runbooks for common failure modes.

Anti-patterns

• Shared database access between independent teams.
• Synchronous chains across many services for one user action.
• Undocumented internal APIs that become production contracts.
• Breaking changes hidden behind deployment coordination.
• Service splits that do not map to ownership boundaries.