API Style
Categorization of design and architectural principles for interfaces (e.g., REST, GraphQL, gRPC) to guide modeling, communication, and error handling.
Classification
- ComplexityMedium
- Impact areaTechnical
- Decision typeArchitectural
- Organizational maturityIntermediate
Technical context
Principles & goals
Use cases & scenarios
Compromises
- Wrong style choice leads to integration issues and technical debt
- Unclear versioning rules cause breaking changes in production
- Lack of observability hampers fault diagnosis
- Clear contracts and automated validation (schema tests)
- Versioning and backward-compatible evolution
- Observability of latency, errors and usage metrics
I/O & resources
- Business requirements and API consumer use cases
- Data model and integration overview
- Operational requirements (SLA, monitoring, security)
- Defined API style, schema and error contracts
- Documentation, SDKs and examples for integrators
- Monitoring and versioning strategy
Description
API style describes the architectural and design choices for a programming interface (e.g., REST, GraphQL, gRPC), defining resource models, communication patterns, and error handling. Choosing an API style has strong effects on scalability, consistency, integration, and operations and requires trade-offs between simplicity, performance, and interoperability.
✔Benefits
- Improved predictability and interoperability between systems
- Targeted optimization for performance or flexibility possible
- Clear expectations for developer teams and integrators
✖Limitations
- No single style fits all use cases
- Enforces trade-offs between simplicity and expressiveness
- Migration between styles can be costly
Trade-offs
Metrics
- Response latency (p95)
Measures the 95th percentile latency for API calls; important for performance comparisons.
- Error rate (5xx)
Share of server errors among all requests; indicator of robustness and stability.
- Throughput (requests/s)
Maximum number of processed requests per second; relevant for scaling decisions.
Examples & implementations
RESTful public API of a payments provider
A payments provider defines resources for payments and accounts, uses HATEOAS elements and strict versioning.
GraphQL interface for a social media frontend
Frontends aggregate various data sources via a GraphQL gateway to minimize roundtrips.
gRPC between microservices in high-throughput area
Performance-intensive services communicate over gRPC with Protobuf schemas for low latency and efficient serialization.
Implementation steps
Requirement analysis and consumer consultation
Evaluate possible API styles with prototypes
Define contracts, versioning and SLAs
Rollout with monitoring, tests and deprecation processes
⚠️ Technical debt & bottlenecks
Technical debt
- Fragmented API landscape without consistent contracts
- Legacy clients forcing breaking changes
- Insufficient test coverage for API compatibility
Known bottlenecks
Misuse examples
- A company replaces an internal RPC system with GraphQL without authentication planning, leading to security gaps.
- Public API changed without versioning and breaks customer integrations.
- Excessive normalization of the resource model leads to many roundtrips and poor performance.
Typical traps
- Underestimating migration costs between styles
- Lack of governance for API changes
- Neglecting observability and SLA definitions
Required skills
Architectural drivers
Constraints
- • Existing client requirements and legacy integrations
- • Organizational governance for API changes
- • Security and privacy requirements