I'm redesigning the public API for our B2B SaaS platform to improve developer experience and future scalability, but I'm struggling to balance consistency with the need to support legacy integrations. I've studied general REST principles, but I need practical advice on nuanced decisions like granularity of endpoints, whether to adopt HATEOAS, and how to version the API without breaking existing clients. For engineers who have maintained and evolved a public API over several years, what design choices did you make early on that you now consider indispensable, and which ones became regrettable technical debt? I'm particularly interested in your approach to error handling, rate limiting, authentication schemes for server-to-server communication, and how you documented the API to be both comprehensive and easily consumable.
Great topic. Start with a clean resource model and versioning in the URL. Keep methods idempotent; use 200/201/204; plan for deprecations early and announce timelines with migration guides.
Indispensable early decisions: keep a small set of core resources that map to business concepts, avoid endpoint sprawl, implement consistent naming, pagination, and a single authentication approach. Decide up front if you want a REST+HATEOAS champion or not.
Error handling: define a uniform envelope: { code, message, details }. Provide a stable error_code mapping; standard HTTP status codes: 400 for bad request, 401/403, 404; 429 for rate limit; 422 for validation. Include examples in docs.
Rate limiting: implement per-key quotas with a leaky/bucket; communicate via headers: X-RateLimit-Remaining, X-RateLimit-Reset; 429 with helpful Retry-After values; ensure burst handling; offer a 'best-effort' mode for non-critical endpoints.
Auth for server-to-server: prefer OAuth2 client credentials or mTLS for internal services. Use short-lived tokens, rotate credentials; scopes for least privilege; separate management tokens; consider binding tokens to origin IP or certificate pinning if you can.
HATEOAS: optional. It helps discoverability but adds maintenance. If you do it, start small (a link section on responses) and evaluate ROI after a year; otherwise focus on excellent docs and strong SDKs.
Documentation and testing: OpenAPI/Swagger; interactive docs; code samples and SDKs; do consumer-driven contract testing; version docs; provide a clear deprecation policy and migration guides. Curious: are you leaning REST-only or exploring GraphQL or gRPC for internal clients? Might tailor advice.