Skip to content
Quality Assurance Labs
Web Development

Backend API & Microservices Architecture Guide

Kawsher, Founder, QA Labs3 min readPublished Updated

APIs are the contract between frontend and backend. Design them like contracts — versioned, documented, authenticated, rate-limited, and monitored. Here's how we architect backend APIs at QA Labs.

Interconnected microservice server pods
  • REST
  • GraphQL
  • microservices
  • API-design
  • backend-architecture

Key takeaways

  • REST for public, GraphQL for complex, tRPC for TS-internal
  • Version from day one
  • Never roll your own auth
  • Rate limit every public endpoint
  • Start with a monolith; split when justified
  • Observability is not optional

Your frontend is only as good as the API it talks to. And your API is only as good as its architecture.

Backend API design is the discipline of building interfaces that are stable, versioned, documented, secure, and observable. Get it right and frontend teams move fast. Get it wrong and every release is a negotiation.

REST vs GraphQL vs tRPC

REST: Best for public APIs, simple CRUD, broad client support. Predictable, cacheable, universal.

GraphQL: Best for complex data graphs, multi-client products, evolving frontends. Powerful, but has learning curve and performance pitfalls (N+1, query complexity).

tRPC: Best for TypeScript monorepos, internal tools. End-to-end type safety, zero codegen.

Pick based on context, not hype. Most teams default to REST for public, GraphQL for complex internal, tRPC for TypeScript-internal.

API versioning

Version your API from day one. Even if you never release v2, the discipline prevents breaking changes.

Options:

URL versioning (/v1/users) — Simple, explicit

Header versioning (Accept: application/vnd.api.v2+json) — Clean URLs

Query parameter (/users?version=2) — Easiest, least clean

URL versioning is the most common. Stick with it.

Authentication and authorization

  • API keys for server-to-server
  • OAuth 2.0 + JWT for user-facing
  • mTLS for high-security internal
  • RBAC or ABAC for authorization

Never roll your own auth. Use battle-tested libraries.

Rate limiting

Every public API needs rate limiting. Common strategies:

  • Per user (100 req/min)
  • Per API key (1000 req/hour)
  • Global (10,000 req/sec)

Return 429 Too Many Requests with Retry-After headers. Document limits publicly.

Microservices — when and when not

Microservices solve specific problems:

  • Different scaling needs per service
  • Different teams owning different domains
  • Different languages for different services
  • Independent deploy cadence

Microservices introduce:

  • Network complexity
  • Distributed tracing needs
  • Distributed data consistency issues
  • Operational overhead

Recommendation: Start with a monolith. Split into services when you have a concrete reason (not theoretical scale).

Observability

  • Logs: Structured JSON, correlation IDs
  • Metrics: Latency (P50/P95/P99), error rate, throughput
  • Traces: Distributed tracing (OpenTelemetry)
  • Alerts: Error rate thresholds, latency thresholds, saturation

You can't operate what you can't observe.

Documentation

Every API needs:

  • OpenAPI spec (Swagger)
  • Auth details
  • Rate limits
  • Error codes
  • Example requests/responses

Generate docs from code where possible. Keep them current.

A production-readiness checklist

  • Every endpoint authenticated and authorised, with tests for both
  • Input validation on every request
  • Rate limits and request size limits set
  • Structured logs, metrics and traces for every service
  • Health checks and alerts on error rate and latency
  • Database migrations tested and reversible
  • API documentation generated from the code or an OpenAPI file

Common mistakes

  • No versioning strategy
  • Rolling your own auth
  • No rate limits
  • No observability
  • Microservices too early
  • Undocumented APIs

Frequently asked questions

  • When do we need microservices? — When separate parts of the system need to scale, deploy or be owned by different teams independently. Before that, a modular monolith is usually simpler and cheaper.
  • REST or GraphQL? — REST is simpler to cache, secure and document, and suits most public APIs. GraphQL suits apps whose screens need flexible combinations of data from many sources.
  • How should we version an API? — Avoid breaking changes where you can. When you must break something, publish a new version, keep the old one running for a stated period and tell clients early.

Free website review

Want a developer to review your website?

Send us your website's address. A developer will check its speed, mobile layout, broken links and forms, and email you the most important fixes, in order of impact. Free, and no call needed.

Related service

Web Development →

Fast, accessible web apps backed by resilient APIs.

Further reading

About the author

Kawsher, Founder, QA Labs →

Kawsher is the founder of Quality Assurance Labs (QA Labs), the QA-first software testing and development company in Bogura, Bangladesh, founded in 2021. Every article and case study on this site is written or reviewed by Kawsher, drawing on the team's QA testing, AI, web, mobile, video and marketing work for SaaS and AI teams worldwide.

Notes from the lab.

Testing, engineering and growth — delivered to your inbox.

Need a backend architecture review? Book a call

Let's talk →