API Design Best Practices: REST vs GraphQL vs gRPC (2026 Guide)

TL;DR

• REST is the right default: well-understood, cacheable, browser-native, and easy to document with OpenAPI/Swagger.
• GraphQL shines when multiple client types need different data shapes from complex, interconnected data models.
• gRPC wins for internal service-to-service communication where performance and strict schema contracts are critical.
• Secure every API with OAuth 2.0 + JWT, rate limiting, and input validation as table stakes.
• Building a proper enterprise API platform costs £15k–£60k depending on complexity and protocol mix.

The Six REST Constraints

• Client-Server: Separation of concerns — the client manages the UI, the server manages data and business logic.
• Stateless: Each request must contain all information needed to process it. No session state stored on the server between requests.
• Cacheable: Responses must define themselves as cacheable or non-cacheable. HTTP caching is a key REST performance advantage.
• Uniform Interface: Resources are identified by URLs, manipulated via representations, and communicated via self-descriptive messages.
• Layered System: Clients cannot tell if they're connected directly to the server or an intermediary (proxy, load balancer, CDN).
• Code on Demand (optional): Servers can extend client functionality by sending executable code (rarely used).

Resource-Based URL Design

URLs represent resources (nouns), not actions (verbs). HTTP methods define the action.

• GET /users — list all users
• GET /users/123 — get user 123
• POST /users — create a new user
• PUT /users/123 — replace user 123 entirely
• PATCH /users/123 — partially update user 123
• DELETE /users/123 — delete user 123

HTTP Status Codes — Use Them Correctly

• 200 OK — successful GET, PUT, PATCH, or DELETE
• 201 Created — successful POST that created a resource (include Location header)
• 204 No Content — successful DELETE with no response body
• 400 Bad Request — client sent invalid data (include error details in body)
• 401 Unauthorized — authentication required or failed
• 403 Forbidden — authenticated but not authorised for this resource
• 404 Not Found — resource does not exist
• 409 Conflict — conflict with current resource state (e.g. duplicate)
• 422 Unprocessable Entity — validation errors (use a structured error response body)
• 429 Too Many Requests — rate limit exceeded (include Retry-After header)
• 500 Internal Server Error — server-side error (never expose stack traces to clients)

Pagination, Filtering, and Sorting

Never return unbounded collections. Implement pagination from day one.

• Cursor-based pagination: GET /orders?cursor=eyJpZCI6MX0&limit=20 — best for real-time data and large datasets
• Offset pagination: GET /orders?page=2&per_page=20 — simpler, fine for static datasets under 10k records
• Filtering: GET /orders?status=pending&created_after=2026-01-01
• Sorting: GET /orders?sort=-created_at,amount (prefix - for descending)
• Return pagination metadata in response: total_count, next_cursor, has_more

Key GraphQL Concepts

• Schema: The contract defining all types, queries, mutations, and subscriptions. Self-documenting and type-safe.
• Queries: Read operations — clients specify exactly which fields they need across multiple related entities in one request.
• Mutations: Write operations — creating, updating, or deleting data.
• Subscriptions: Real-time data via WebSocket — clients subscribe to data changes (e.g., live order status updates for Australian e-commerce platforms).
• Resolvers: Server-side functions that resolve each field in a query — the core business logic layer.

The N+1 Problem — GraphQL's Main Pitfall

When a GraphQL query fetches a list of N entities and then resolves a related field for each one, it can trigger N+1 database queries (one for the list, one per item). This is the most common performance issue in GraphQL implementations. The solution is the DataLoader pattern — batching and caching database calls across all resolvers in a single request cycle. Always implement DataLoader before going to production with GraphQL.

gRPC Communication Patterns

• Unary RPC: Single request, single response — equivalent to a REST call.
• Server streaming: Single request, stream of responses — useful for event feeds and progress reporting.
• Client streaming: Stream of requests, single response — useful for file uploads or telemetry ingestion.
• Bidirectional streaming: Both sides send a stream of messages simultaneously — ideal for real-time chat, collaborative editing, and gaming backends.

OAuth 2.0 and JWT

OAuth 2.0 is the industry standard for delegated authorisation, used by every major platform from UK government APIs to US enterprise SaaS. Use the Authorization Code Flow with PKCE for user-facing applications and the Client Credentials Flow for machine-to-machine API access. JWT (JSON Web Tokens) are the standard format for access tokens — encode the user's identity and permissions, sign with RS256 or ES256, and keep lifetimes short (15 minutes for access tokens, 7 days for refresh tokens).

Rate Limiting

Implement rate limiting at the API gateway level to protect against abuse, denial-of-service, and credential stuffing. Common strategies include fixed window (e.g., 1,000 requests per hour per client), sliding window, and token bucket. Return 429 Too Many Requests with a Retry-After header. Expose rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. This is a GDPR-relevant consideration for APIs operating in the UK and Europe — logging who hit rate limits can be personal data.

Input Validation and Injection Prevention

Validate every input on the server side, regardless of client-side validation. Use schema validation libraries (Pydantic for Python, Zod for TypeScript, Jakarta Bean Validation for Java). Parameterise all database queries to prevent SQL injection. For GraphQL, implement query depth limits and query complexity scoring to prevent resource exhaustion attacks from deeply nested queries.

Deprecation Policy Best Practice: For public APIs serving clients in the UK, US, Canada, Australia and Europe, provide a minimum 12-month deprecation window. Announce deprecations in API response headers (Deprecation: true, Sunset: Sat, 31 Dec 2027 00:00:00 GMT), via email to registered developers, and in your changelog. Never silently remove endpoints.

OpenAPI (formerly Swagger)

The OpenAPI Specification (OAS) is the de-facto standard for describing REST APIs. Write your API spec in YAML or JSON, and tools like Swagger UI, Redoc, or Scalar automatically generate interactive documentation. Benefits: automatic client SDK generation in 40+ languages, validation tooling, contract testing. Define your OAS spec first (design-first) before writing any code — this forces cleaner API design and enables parallel frontend/backend development.

Postman and Developer Portals

Publish Postman collections alongside your OpenAPI spec. A developer portal (built on tools like Mintlify, ReadMe, or Stoplight) with live API explorers, authentication guides, and code examples in multiple languages dramatically reduces integration time for clients in the US, Canada, Australia and Europe. Treat your API docs as a first-class product — assign ownership, keep them current, and include real request/response examples.

Critical Webhook Best Practices

• Sign every webhook payload with HMAC-SHA256 using a shared secret. Clients verify the signature before processing. This prevents spoofed events from malicious actors.
• Include a unique event ID in every payload to enable idempotency — clients should deduplicate events they've already processed.
• Retry with exponential backoff when clients return non-200 responses. Retry after 1 min, 5 min, 30 min, 2 hours, 24 hours before giving up.
• Send minimal event payloads and have clients fetch full data via your API if needed (fetch-on-receive pattern). Reduces payload size and avoids stale data in retried events.
• Provide a webhook dashboard showing event history, delivery status, and retry logs. This dramatically reduces support burden for UK and US enterprise clients.
• Use a queue (SQS, Pub/Sub) between your event source and the webhook delivery system — never call client endpoints synchronously from your core application.

Simple REST API (CRUD + Auth): £15,000–£30,000

A well-designed REST API with authentication, rate limiting, documentation, and a basic developer portal. Timeline: 8–14 weeks. Suitable for internal tools, simple integrations, and SaaS MVP backends for UK or Canadian startups.

Enterprise API Platform (REST + GraphQL + Webhooks): £35,000–£60,000

Includes an API gateway, multiple API protocols, comprehensive documentation portal, webhook system with retry logic, analytics, and developer onboarding flows. Timeline: 16–24 weeks. Appropriate for high-growth SaaS platforms serving enterprise clients across US, UK, Europe, and Australia.