I'm leading the redesign of our legacy internal REST API to support both web and mobile clients, and I'm trying to establish clear design principles before we start coding. I'm stuck on several foundational decisions, particularly around versioning strategies, hypermedia controls versus simple JSON endpoints, and granularity of resources. For architects who have designed large-scale, maintainable APIs, what are your non-negotiable best practices? How do you balance consistency with flexibility, especially when dealing with nested resources and complex queries? What has been your experience with tools like OpenAPI for specification-first development, and how do you effectively document error handling and rate limiting for client developers?
Reply 1: Two big-picture takes I’ve found useful: pick a single, stable versioning strategy and honor it. In practice I prefer in-path versioning (/api/v1/…), with a documented deprecation policy (e.g., 12–24 months notice, automatic fallback). That gives clients a predictable upgrade path and avoids breaking existing apps. Also implement a simple Problem Details (RFC 7807) error schema and a short deprecation notice in responses so teams aren’t blindsided.
Reply 2: OpenAPI-driven development pays off for maintainability. Treat the OpenAPI spec as the source of truth; generate server stubs and client SDKs when possible; add contract tests (PACT or similar) to lock in expectations. Pair with a lightweight CI gate that prevents merging breaking changes. For docs, host Redoc or Swagger UI from the canonical spec; ensure a changelog and migration notes accompany each release.
Reply 3: Hypermedia is seductive but not always worth it for internal tools. If you do use hypermedia, pick a simple standard (HAL or JSON:API) and keep it optional. For many teams, a clean, well-documented REST surface with explicit links to related resources is enough and reduces coupling.
Reply 4: Granularity and nested resources: avoid over-nesting. Expose core resources and provide relations via IDs or links; allow expand parameters to fetch related data in a single call but guard against heavy joins. Consider flags to fetch just id, or embed summary payloads with a separate endpoint to fetch details. Think in terms of CRUD edges rather than deep trees.
Reply 5: Operational tips: pagination (cursor-based if you have real-time data; page+size for simple), filtering and sorting essentials, and proper indexing on DB queries; caching with ETag/Last-Modified; implement rate limiting and quotas at the gateway; include observability: metrics on latency, error rate, and cache hit rate; plan for security: OAuth2 scopes or API keys; ensure auditing and logs.