API Design Best Practices in 2026: REST, GraphQL, and tRPC

"Should we use REST or GraphQL?" is the wrong question. After shipping 25+ production APIs across seven countries, I can tell you the API design best practices in 2026 start with a different question entirely: what is the relationship between your API's producer and its consumer? Get that right, and the choice between REST, GraphQL, tRPC, and gRPC becomes obvious. Get it wrong, and you will spend the next two years apologizing to your team and your customers.

I am Khaled Ahmed, a senior full stack web developer based in Cairo. Over the last five years I have designed APIs for fintech in Switzerland, healthcare platforms in Germany, e-commerce systems in Saudi Arabia and the UAE, government portals in Egypt, and SaaS products in the UK, France, and Kuwait. The patterns that work are surprisingly consistent. The mistakes that kill projects are even more consistent. This article is the playbook I wish I had when I started — opinionated, specific, and tested under real production load.

What "API design" actually means in 2026 (and why the REST vs GraphQL debate is dead)

Ten years ago, "API design" meant choosing endpoints and writing Swagger docs. In 2026 it means something much bigger: defining the contract between systems that may be owned by different teams, written in different languages, deployed in different clouds, and consumed by clients ranging from a React Native app to an autonomous AI agent making 4,000 calls per minute.

The modern API design principles I follow on every project cover six concerns that did not exist in the 2015 textbooks:

• Type safety end-to-end — your backend types should flow through to your frontend without manual duplication.
• Schema-first or code-first contracts — OpenAPI 3.1 specification, GraphQL SDL, or Protocol Buffers, generated from code so they never drift.
• Idempotency — every mutation needs to handle retries safely, because networks are unreliable and AI agents do not know what "click once" means.
• Observability — distributed tracing, structured logs, and metrics baked into the API surface, not bolted on.
• Cost-awareness — when an AI agent can fan out 1,000 GraphQL queries before lunch, you need persisted queries and complexity limits.
• Backward compatibility as a feature — your API versioning strategy is a product decision, not an engineering afterthought.

The "REST vs GraphQL vs tRPC" framing treats these as competing religions. They are not. They are tools that solve different problems for different consumers. Stop arguing about which one is "better" and start asking who will actually call your API.

The only question that matters: who consumes your API?

Every architectural decision flows from this one question. I make the entire team answer it in writing before we draw a single endpoint:

1. Third parties you do not control (developers, partners, public users with API keys) → REST, always. They expect curl-friendly endpoints, standard HTTP semantics, and stable URLs they can bookmark.
2. Your own frontend team in the same company, sharing a complex domain model across web, mobile, and admin clients → GraphQL is often the right answer.
3. Your own team, all TypeScript, all in one monorepo → tRPC will ship faster than anything else and catch bugs at compile time.
4. Internal microservices talking to each other at high throughput with strict schemas → gRPC with Protocol Buffers.
5. AI agents and LLM tools → REST with rich OpenAPI descriptions, because that is what tool-calling models consume natively in 2026.

That single taxonomy has prevented more architecture mistakes than every "clean code" book combined. I have seen teams choose GraphQL because it sounded modern and then spend 18 months fighting caching, authorization, and N+1 queries — when a boring REST API would have shipped in three months.

REST in 2026: still the default for public and third-party APIs

REST is twenty-six years old and somehow still the right choice most of the time. Here is why: HTTP is the only protocol you can assume every client, proxy, CDN, browser, and tool understands without configuration. That is enormous. Cacheable by design, debuggable with curl, monitorable by every APM tool ever built.

For public APIs, third-party integrations, and any API consumed by parties you do not control — REST is still the right answer. The companies that tried to "GraphQL all the things" for public APIs (Shopify, GitHub) have quietly maintained their REST APIs in parallel because their customers demanded it. Stripe, Twilio, and AWS — the gold standard for developer experience — are all REST. Pattern recognition matters.

If your API is consumed by people whose code review you cannot attend, give them REST. Anything else is a tax on your customers, and they will eventually leave for an alternative that does not tax them.

REST done right: resources, verbs, status codes, and HATEOAS

"REST" gets used to mean "any JSON over HTTP," but real REST has rules. Here is how to design a REST API that does not embarrass you in two years:

• Resource-based URLs — /api/v1/users/123/orders, not /api/getUserOrders?id=123. Nouns, not verbs.
• Use HTTP verbs correctly — GET (safe, idempotent), POST (create), PUT (full replace, idempotent), PATCH (partial update), DELETE (idempotent). If your DELETE is not idempotent, you have a bug.
• Return appropriate status codes — 200 for success, 201 for created with Location header, 204 for no content, 400 for validation errors, 401 for unauthenticated, 403 for unauthorized, 404 for not found, 409 for conflicts, 422 for unprocessable entities, 429 for rate limited, 500 for server errors. Anything else needs justification.
• Version from day one — /api/v1/ in the URL is boring and works. Header-based versioning is academically pure and operationally painful.
• Pagination, filtering, sorting via query params — ?page=2&per_page=50&sort=-created_at&filter[status]=active.
• Rate limiting headers — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on 429.
• HATEOAS where it makes sense — return links to related resources in responses. Pure HATEOAS is overkill for most apps, but a _links object pointing to next/prev pages and related resources reduces client coupling.
• Idempotency keys on POST requests that create resources, so retries do not double-charge customers.

Here is what a well-designed POST endpoint looks like in Laravel — the framework I use for most backend work:

// routes/api.php
Route::middleware(['auth:sanctum', 'throttle:60,1'])
    ->prefix('v1')
    ->group(function () {
        Route::post('orders', [OrderController::class, 'store']);
    });

// app/Http/Controllers/Api/V1/OrderController.php
public function store(StoreOrderRequest $request)
{
    $idempotencyKey = $request->header('Idempotency-Key');

    if ($idempotencyKey && $existing = Order::where('idempotency_key', $idempotencyKey)->first()) {
        return new OrderResource($existing);
    }

    $order = DB::transaction(function () use ($request, $idempotencyKey) {
        return Order::create([
            ...$request->validated(),
            'user_id' => $request->user()->id,
            'idempotency_key' => $idempotencyKey,
        ]);
    });

    return (new OrderResource($order))
        ->response()
        ->setStatusCode(201)
        ->header('Location', route('api.v1.orders.show', $order));
}

That is fewer than 30 lines and it covers authentication, rate limiting, validation, idempotency, transactions, proper status codes, and the Location header. This is the baseline. Anything less is incomplete.

HTTP status codes cheat sheet (200, 201, 400, 401, 403, 404, 409, 422, 429, 500)

I have lost count of how many code reviews I have left a "this should be a 422, not a 400" comment. Status codes are not aesthetic preferences — they are the contract clients rely on to know what to do next.

• 200 OK — successful GET, PUT, PATCH, or DELETE with response body.
• 201 Created — successful POST that created a resource. Include Location header.
• 202 Accepted — request queued for async processing. Return a status URL.
• 204 No Content — successful DELETE with no body, or successful PUT/PATCH where the client does not need the updated resource.
• 301/302 — only for URL changes. Never for normal API flow.
• 400 Bad Request — malformed JSON, missing required fields at parse time. Use 422 for business validation failures.
• 401 Unauthorized — missing or invalid authentication. The user needs to log in.
• 403 Forbidden — authenticated but not allowed. Do not leak resource existence.
• 404 Not Found — resource does not exist, or 403 disguised as 404 to prevent enumeration.
• 409 Conflict — state conflict, like duplicate slug or stale optimistic-lock version.
• 410 Gone — resource intentionally removed. Use when you delete a deprecated endpoint in a future version.
• 422 Unprocessable Entity — valid syntax but business rules rejected it. Most validation errors live here.
• 429 Too Many Requests — rate limited. Always include Retry-After.
• 500 Internal Server Error — unhandled exception. This should page your on-call.
• 503 Service Unavailable — planned maintenance or temporary overload. Include Retry-After.

Pagination patterns: offset vs cursor vs keyset (with benchmarks)

This is the single most common mistake I see in code reviews: LIMIT 50 OFFSET 100000. On a 10-million-row table that query takes 2.4 seconds in PostgreSQL because the database has to scan 100,050 rows just to throw 100,000 away. Cursor pagination on the same table runs in 3 milliseconds. That is a 800x speedup from a one-day refactor.

Here is when to use each:

• Offset pagination (?page=2&per_page=50) — fine for small datasets (<10,000 rows) and admin tables where users jump to page 47. Easy to implement, easy to understand, slow at scale.
• Cursor pagination (?cursor=eyJpZCI6MTIzfQ&limit=50) — the right default for any feed-like endpoint. Encodes the last-seen sort key as an opaque base64 cursor. Stable when new items are inserted, fast at any scale.
• Keyset pagination (?after_id=12345&limit=50) — cursor pagination with a transparent key. Use when consumers benefit from constructing the next URL manually.

Here is a cursor pagination implementation that I use in production for an e-commerce platform serving 80,000 daily users:

// app/Services/CursorPaginator.php
public function paginate(Builder $query, ?string $cursor, int $limit = 50): array
{
    $decoded = $cursor ? json_decode(base64_decode($cursor), true) : null;

    if ($decoded) {
        $query->where(function ($q) use ($decoded) {
            $q->where('created_at', '<', $decoded['created_at'])
              ->orWhere(function ($q2) use ($decoded) {
                  $q2->where('created_at', '=', $decoded['created_at'])
                     ->where('id', '<', $decoded['id']);
              });
        });
    }

    $items = $query->orderByDesc('created_at')
                   ->orderByDesc('id')
                   ->limit($limit + 1)
                   ->get();

    $hasMore = $items->count() > $limit;
    $items = $items->take($limit);

    $nextCursor = $hasMore ? base64_encode(json_encode([
        'created_at' => $items->last()->created_at->toIso8601String(),
        'id' => $items->last()->id,
    ])) : null;

    return ['data' => $items, 'next_cursor' => $nextCursor];
}

The tie-breaker on id matters — without it, two rows with identical timestamps cause the paginator to skip items. I have debugged this exact bug three times in three different companies.

GraphQL in 2026: when one schema beats fifty endpoints

GraphQL shines when frontend and backend are owned by the same organization and the frontend has diverse data needs — a mobile app, a web app, and an admin panel all hitting the same API. It eliminates over-fetching, eliminates under-fetching, and lets product teams move without backend coordination for every new screen.

I have shipped GraphQL successfully on three projects:

• A real estate platform in Dubai where the same listings data feeds a public search page, a logged-in dashboard, and an internal CMS — each needs different fields.
• A logistics dashboard in Germany where management screens compose data from five microservices behind a single Apollo Federation gateway.
• An internal admin tool in Cairo where the product team wanted to build screens without waiting for a backend ticket on every new field.

When NOT to use GraphQL: the API is consumed by third parties, caching is critical, your team has not used it before, or your data is more transactional than graph-like. Operational complexity is real and underestimated. Authorization at field level is harder than route-based authorization. Rate limiting becomes query complexity analysis. Monitoring becomes tracing across resolvers instead of HTTP routes.

GraphQL pitfalls: N+1 queries, caching nightmares, and over-fetching myths

Every GraphQL project I have inherited has had at least three of these problems:

1. N+1 queries everywhere — resolvers that look innocent (posts -> author) actually run one SQL query per post. Fix: DataLoader on every relationship. Not optional.
2. No query depth or complexity limits — a malicious client sends users { friends { friends { friends { ... } } } } and brings the database to its knees. Fix: complexity scoring with a hard cap (I use 1000 as a baseline).
3. Authorization scattered across resolvers — every resolver re-checks "can this user see this field?" Fix: a centralized policy layer, or use Apollo's schema directives.
4. HTTP caching abandoned — everything is POST, so CDN caching is dead. Fix: persisted queries with GET requests for queries that are cacheable.
5. Versioning chaos — "GraphQL does not need versioning" is the lie that creates 80-field types with 40 deprecated fields nobody dares remove. Fix: actually use @deprecated and run usage analytics to know when fields are safe to delete.

The "GraphQL eliminates over-fetching" claim is technically true but practically misleading. In my experience, the bigger savings come from under-fetching elimination — collapsing six round-trips into one. The over-fetching reduction is marginal because most fields are cheap to serialize anyway.

Apollo Federation vs schema stitching vs monolithic GraphQL

Three ways to scale a GraphQL API across teams. Here is my honest assessment after using all three in production:

• Monolithic GraphQL — one schema, one server, one deployment. Boring and correct for teams under 30 engineers. Do not over-engineer.
• Apollo Federation v2 — multiple subgraphs composed by a gateway. The right choice when you have multiple backend teams owning different domains. Solid tooling, real operational cost (gateway is now a critical path single point of failure that must scale to 100% of traffic).
• Schema stitching — the legacy approach. Avoid. Use Federation v2 instead.

I picked Federation for the logistics project because we had five backend teams already. I would not have picked it for a single team — the gateway adds 15ms of latency and a whole new deployable that needs its own SLO. Good database design matters more than your GraphQL topology for performance.

tRPC: end-to-end type safety for TypeScript monorepos

If both ends are TypeScript — Next.js front, Node backend, single repo — tRPC gives you end-to-end type safety with zero schema duplication. No code generation, no schema files, no synchronization step. Your frontend autocompletes backend types because they literally are backend types.

I have used tRPC on five projects in the last 18 months, all greenfield SaaS products in the Next.js ecosystem. Build velocity goes up by something like 30% because there is no contract drift, no manual TypeScript types for API responses, and no Postman collection to maintain. Refactoring is genuinely safe — rename a field on the server and the frontend stops compiling until you fix it.

A typical tRPC router looks like this:

// server/routers/orders.ts
import { z } from 'zod';
import { protectedProcedure, router } from '../trpc';

export const ordersRouter = router({
  list: protectedProcedure
    .input(z.object({
      cursor: z.string().nullish(),
      limit: z.number().min(1).max(100).default(50),
    }))
    .query(async ({ ctx, input }) => {
      const items = await ctx.db.order.findMany({
        where: { userId: ctx.user.id },
        take: input.limit + 1,
        cursor: input.cursor ? { id: input.cursor } : undefined,
        orderBy: { createdAt: 'desc' },
      });

      const nextCursor = items.length > input.limit ? items.pop()!.id : null;
      return { items, nextCursor };
    }),

  create: protectedProcedure
    .input(z.object({
      productId: z.string().uuid(),
      quantity: z.number().int().positive(),
    }))
    .mutation(async ({ ctx, input }) => {
      return ctx.db.order.create({
        data: { ...input, userId: ctx.user.id },
      });
    }),
});

On the frontend:

// app/orders/page.tsx
'use client';
import { trpc } from '@/lib/trpc';

export default function OrdersPage() {
  const { data, fetchNextPage, hasNextPage } = trpc.orders.list.useInfiniteQuery(
    { limit: 50 },
    { getNextPageParam: (last) => last.nextCursor }
  );

  // data.pages is fully typed. No types file. No codegen.
  return (...);
}

Zod schema validation runs at the boundary, the Prisma return type flows to the frontend, and the React Query integration handles caching and refetching. This is what 2026 backend development looks like when you control both ends. If you are building a SaaS MVP with a small team, tRPC is often the fastest path to production.

When NOT to use tRPC: public APIs (no standard schema for outside consumers), polyglot backends (it is TypeScript-only by design), or when you anticipate the backend being rewritten in another language. tRPC is a productivity multiplier for the specific case it was designed for — do not stretch it.

tRPC vs GraphQL vs REST: a head-to-head comparison table

Here is the comparison I share with clients deciding their stack. I will narrate it as a structured list because the original "table" intent matters more than the visual format:

• REST — Type safety: manual via OpenAPI generators. Caching: native HTTP. Tooling: universal. Public API: yes. Learning curve: low. Best for: third-party APIs, mobile SDKs, AI agent tools.
• GraphQL — Type safety: schema-based with codegen. Caching: client-side via Apollo/Relay, no HTTP caching. Tooling: excellent (GraphiQL, Apollo Studio). Public API: technically yes, practically painful. Learning curve: medium-high. Best for: large frontends with diverse data needs, federated microservices.
• tRPC — Type safety: end-to-end automatic. Caching: React Query integration. Tooling: TypeScript-native, no separate IDE needed. Public API: no. Learning curve: low if you know TypeScript. Best for: TypeScript monorepos, internal APIs, fast iteration.
• gRPC — Type safety: Protocol Buffers generated. Caching: limited (binary protocol). Tooling: strong for backend, weak for browsers. Public API: rare, used by Google/etcd-style projects. Learning curve: high. Best for: internal microservice-to-microservice traffic, real-time bidirectional streaming.

gRPC and Protocol Buffers: when binary protocols win

gRPC and Protocol Buffers earn their place in two specific cases: high-throughput internal microservice communication, and bidirectional streaming where WebSockets feel under-specified. The binary serialization is roughly 5-7x smaller than JSON and 3-4x faster to parse. For an order service that ingests 50,000 events per second from a payment service, that matters.

What I have learned about gRPC after deploying it on a Swiss fintech project:

• The browser support story is still messy. gRPC-Web works but requires a proxy. For browser-facing APIs, stick with REST or GraphQL.
• The proto file becomes a critical shared artifact. Treat it like a versioned package, not a file you check in to each service.
• Deadlines and cancellation propagation are first-class. This is one area where gRPC genuinely beats HTTP.
• Observability requires gRPC-aware tooling. Most APM products handle it now, but verify before you commit.

Real-time APIs: WebSockets, Server-Sent Events, and GraphQL subscriptions

"Real-time" means three different things in 2026, and choosing the wrong one wastes weeks:

1. Server-Sent Events (SSE) — server pushes events to client over plain HTTP. One-way, simple, works through every proxy. Use for notifications, live dashboards, AI streaming responses. This is what ChatGPT-style typing effects use.
2. WebSockets — bidirectional persistent connection. Use for chat, collaborative editing, multiplayer games. More operational complexity (sticky sessions, reconnection logic, scaling considerations).
3. GraphQL subscriptions — typically WebSockets under the hood, with a schema. Use when you are already on GraphQL and want consistency.
4. Long polling — fall back when WebSockets and SSE are blocked by corporate proxies. Still exists. Still works.
5. HTTP/2 server push — effectively deprecated. Do not design around it.

My default in 2026 is SSE for server-to-client streams and WebSockets only when bidirectional traffic is genuinely needed. SSE is criminally underrated — it solves 80% of "real-time" requirements with 20% of the complexity of WebSockets.

The decision tree: choosing REST, GraphQL, tRPC, or gRPC in 5 questions

This is the API design decision tree I walk every client through:

1. Is this API consumed by parties you do not control? → REST. Stop here.
2. Is your backend and frontend both TypeScript in one monorepo? → tRPC. Ship faster than the alternatives.
3. Do you have multiple frontend clients (web, mobile, admin) hitting the same data graph, all owned by your team? → GraphQL.
4. Is this internal microservice-to-microservice traffic at high throughput? → gRPC.
5. Do you need real-time? → Add SSE or WebSockets on top of whatever you chose in 1-4.

That is it. Five questions, defensible answers. The mistake I see most often is teams skipping question 1 and choosing GraphQL for a public API because it sounds modern. Then they spend two years rebuilding REST endpoints because customers demanded them. Do not be that team.

Authentication and authorization: JWT, sessions, OAuth 2.1, and API keys

API authentication best practices in 2026 split by use case:

• First-party web apps — session cookies with HttpOnly, Secure, SameSite=Lax. Boring and correct. JWT in localStorage is a security mistake people keep making because tutorials taught them wrong.
• Mobile apps and SPAs — short-lived JWT access tokens (15 min) with refresh tokens stored in secure storage. Rotate refresh tokens on use.
• Third-party integrations (developer APIs) — API keys with scopes. Display once, hash in the database, allow per-key rate limits and revocation.
• Server-to-server — mTLS or signed JWTs with short TTL. API keys work too but are harder to rotate.
• User-delegated access (your users letting their data be accessed by another app) — OAuth 2.1 with PKCE. The PKCE flow is now mandatory for all clients in OAuth 2.1, not just public ones.

The JWT vs session cookies debate is largely settled: cookies for browser clients, JWT for everything else. Cookies give you CSRF protection via SameSite, automatic browser handling, and built-in expiration. JWT gives you statelessness, which matters when your auth server and your API are different services. Pick based on architecture, not aesthetics. Read my website security checklist for the broader picture.

Rate limiting strategies: token bucket, sliding window, and Redis implementation

Every public-facing API needs rate limiting, full stop. The question is which algorithm:

• Fixed window — count requests per minute, reset on the minute. Simple, but allows 2x burst at window boundaries. Not recommended.
• Sliding window log — store timestamp of every request, count those in the last N seconds. Accurate but memory-hungry.
• Sliding window counter — weighted average of current and previous window. Good middle ground. This is what Cloudflare uses.
• Token bucket — replenish tokens at a fixed rate, requests consume tokens. Allows controlled bursts. My default for most APIs.

Here is a Redis-backed token bucket implementation in PHP that I use across multiple Laravel projects:

// app/Services/RateLimiter.php
public function consume(string $key, int $capacity, int $refillPerSecond): bool
{
    $now = microtime(true);
    $lua = <<<LUA
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local refill = tonumber(ARGV[2])
local now = tonumber(ARGV[3])

local bucket = redis.call('HMGET', key, 'tokens', 'last')
local tokens = tonumber(bucket[1]) or capacity
local last = tonumber(bucket[2]) or now

local elapsed = now - last
tokens = math.min(capacity, tokens + elapsed * refill)

if tokens < 1 then
  redis.call('HMSET', key, 'tokens', tokens, 'last', now)
  redis.call('EXPIRE', key, 3600)
  return 0
end

tokens = tokens - 1
redis.call('HMSET', key, 'tokens', tokens, 'last', now)
redis.call('EXPIRE', key, 3600)
return 1
LUA;

    return (bool) Redis::eval($lua, 1, "rl:{$key}", $capacity, $refillPerSecond, $now);
}

The Lua script makes the read-modify-write atomic, which matters at high concurrency. A naive PHP implementation would have a race condition that lets through 2-3x the rate limit under load. I learned this the hard way on a Black Friday sale that DDoS'd our own database.

Versioning APIs without breaking clients: URL, header, and content negotiation

Your API versioning strategy is a promise to customers. Get it wrong and you cannot fix it without breaking them. Three approaches:

• URL versioning (/api/v1/users) — boring, visible, easy to route in load balancers. My default for public APIs.
• Header versioning (Accept: application/vnd.myapi.v2+json) — clean URLs, harder to curl, harder to cache. Theoretically pure, practically annoying.
• Date-based versioning (Stripe-Version: 2024-06-20) — Stripe's approach. Excellent for APIs that evolve constantly without major redesigns. Customers pin to a date and migrate on their schedule.

Rules I follow:

1. Version from day one, even on v1. Adding versioning later is a customer-breaking change in itself.
2. Additive changes (new optional fields, new endpoints) do not require a version bump.
3. Breaking changes (removing fields, changing types, changing semantics) require a new version.
4. Support old versions for at least 12 months after deprecation. Two years for paid customers.
5. Sunset headers (Sunset: Sat, 31 Dec 2026 23:59:59 GMT) let clients know when an endpoint goes away.

Error handling with RFC 7807 problem+json

RFC 7807 problem details is the standard for structured API errors, and almost no one uses it. They should. Here is what a proper error response looks like:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation-failed",
  "title": "Your request parameters did not validate",
  "status": 422,
  "detail": "The 'email' field is required and 'age' must be between 18 and 120",
  "instance": "/api/v1/users",
  "errors": [
    {
      "field": "email",
      "rule": "required",
      "message": "The email field is required"
    },
    {
      "field": "age",
      "rule": "between",
      "message": "The age must be between 18 and 120"
    }
  ],
  "trace_id": "01HXYZ123ABCDEF456GH"
}

The type URL is the killer feature — it can link to documentation explaining the error class. trace_id lets the customer reference a specific failure when they email support, and you can pull the exact request from your logs. Good debugging starts with good error responses.

API documentation: generating OpenAPI from code (Laravel, NestJS, FastAPI)

OpenAPI specification 2026 (3.1 is the current version, finally aligning with JSON Schema) is the de facto standard for documenting REST APIs. The rule I enforce on every team: your OpenAPI spec must be generated from code, never written by hand. Hand-written specs always drift from reality. Generated specs cannot lie.

Per framework:

• Laravel — Scramble (newer, zero-config) or L5-Swagger (more mature, requires annotations). I use Scramble on new projects because it infers most things from type hints and form requests.
• NestJS — @nestjs/swagger is built-in, generated from your DTOs and decorators. Best-in-class developer experience in the Node ecosystem.
• FastAPI — OpenAPI generation is the default behavior. This is why FastAPI has eaten Flask's lunch in Python.
• Express — use express-openapi-validator if you want spec-first, or migrate to tRPC if you are TypeScript-only.

From the OpenAPI spec, you can generate client SDKs in 30+ languages, Postman collections, mock servers, and contract tests. That is enormous leverage from one source of truth. JSON:API specification is an alternative for opinionated REST, but OpenAPI is the lingua franca.

Security hardening: CORS, CSRF, input validation, and the OWASP API Top 10

The OWASP API Top 10 reads like a confession of every API I have ever audited. The top three killers in 2026:

1. Broken Object Level Authorization (BOLA) — endpoint returns /api/v1/orders/123 without checking that order 123 belongs to the authenticated user. This is the #1 vulnerability in production APIs. Test every authenticated endpoint with a wrong user's ID.
2. Broken Authentication — no rate limit on login, no MFA, JWT secrets in source control, predictable session IDs. Boring problems that still cause breaches.
3. Excessive Data Exposure — your User model serializes password_hash, internal_notes, and stripe_customer_id because someone returned $user->toArray(). Use explicit Resource/DTO classes always.

Other essentials:

• CORS — explicit origin allowlist, never Access-Control-Allow-Origin: * on authenticated APIs.
• CSRF — required for cookie-based auth. Not required for token-based auth in Authorization headers.
• Input validation — Zod, Joi, Laravel form requests, FastAPI Pydantic models. Validate at the boundary, trust internally.
• Output encoding — set Content-Type explicitly, set X-Content-Type-Options: nosniff.
• Security headers — HSTS, CSP, X-Frame-Options. See my full security checklist for the complete list.

Performance: caching layers, CDN integration, and response compression

API performance lives or dies at four layers:

1. Database — indexes, query plans, connection pooling. Database design is upstream of API performance.
2. Application cache — Redis for hot data, with explicit invalidation. Cache the SQL results, not the JSON response.
3. HTTP cache — ETag and Last-Modified headers, Cache-Control with stale-while-revalidate. Lets CDNs and browsers do work for you.
4. CDN — Cloudflare, Fastly, Bunny. Cache GET responses at the edge for endpoints that allow it.

Response compression: enable Brotli for everything. Brotli 4 gives you 90% of the compression at 30% of the CPU cost compared to Brotli 11. Most cloud platforms enable it automatically; verify with curl -H "Accept-Encoding: br" -I.

ETag caching example for a Laravel API:

// app/Http/Middleware/EtagMiddleware.php
public function handle($request, Closure $next)
{
    $response = $next($request);

    if ($request->isMethod('GET') && $response->getStatusCode() === 200) {
        $etag = '"' . md5($response->getContent()) . '"';
        $response->header('ETag', $etag);
        $response->header('Cache-Control', 'private, max-age=60, stale-while-revalidate=300');

        if ($request->header('If-None-Match') === $etag) {
            return response('', 304)->header('ETag', $etag);
        }
    }

    return $response;
}

A 304 Not Modified response is roughly 200 bytes versus a typical 50KB JSON response. On a feed endpoint hit 1 million times a day, that is 50 GB of bandwidth saved. Not theoretical — measured on the e-commerce platform I mentioned earlier.

Common API design mistakes I see in code reviews (and how to fix them)

Patterns I flag on almost every code review:

• Verbs in URLs — /api/createUser instead of POST to /api/users. Fix: use HTTP verbs.
• 200 OK for everything — including errors, with a success: false field. Fix: use HTTP status codes correctly.
• Returning database column names — user_id, created_at_utc, is_deleted_flag. Fix: explicit Resource/Serializer layer.
• No pagination on list endpoints — works on day one, dies at 10,000 rows. Fix: cursor pagination from the start.
• Mutating GET endpoints — GET /api/orders/123/complete. Fix: POST to /api/orders/123/completions.
• Massive composite endpoints — POST /api/process that does seven different things based on a type field. Fix: separate endpoints, or move to GraphQL.
• Plain text passwords in request logs — yes, still. Fix: scrub sensitive fields in your logging middleware.
• No request ID propagation — debugging requires grep across 12 services. Fix: X-Request-Id header generated at the gateway, propagated through every internal call.
• Inconsistent field naming — userId in one endpoint, user_id in another. Fix: linter rule on the OpenAPI spec.
• Time zones in local time — always return ISO 8601 with explicit UTC offset (2026-06-20T15:30:00Z).

The future of APIs: AsyncAPI, event-driven architecture, and AI agent endpoints

What is coming in the next 24 months that you should plan for:

• AsyncAPI — the OpenAPI equivalent for event-driven systems (Kafka, RabbitMQ, MQTT). If you are publishing events, document them with AsyncAPI 3.0.
• AI agent endpoints — your API is increasingly called by LLM tool-use, not by humans. Rich OpenAPI descriptions, idempotency keys, and clear error messages matter more than they used to. The agent needs to recover from errors without human intervention.
• Model Context Protocol (MCP) — Anthropic's standard for AI-to-tool communication. Worth tracking if your product will be consumed by AI assistants.
• HTTP/3 and QUIC — already at ~30% of internet traffic. Make sure your CDN and load balancer support it.
• Edge compute — your API gateway is increasingly a Cloudflare Worker or Vercel Edge Function, not a Kubernetes pod. This pushes auth and rate limiting to the edge.
• Webhooks done right — signed payloads, retries with exponential backoff, idempotency, replay endpoints. Stripe is the reference implementation.

If you are building for the next five years, design your API surface assuming half your traffic will eventually be from automated agents — including ones you do not control. That changes how seriously you take rate limiting, idempotency, and error messages.

FAQs about API design best practices in 2026

Is REST dead in 2026?

No, and it will not be for the foreseeable future. REST is still the right choice for public APIs, third-party integrations, mobile SDKs, and any context where you need maximum compatibility with the existing ecosystem of HTTP tooling. The argument is not REST vs alternatives — it is using the right tool for each consumer. Stripe is REST. Twilio is REST. The Anthropic API is REST. Pattern recognition matters.

When should I choose GraphQL over REST?

When your API is internal to your organization, you have multiple frontend clients (web, mobile, admin) with diverse data needs, and your team has the operational maturity to handle query complexity limits, DataLoader, and field-level authorization. Do not choose GraphQL because it is trendy. Choose it because you have under-fetching pain that REST cannot solve elegantly.

Is tRPC production-ready?

Yes, very much so. I have shipped tRPC on five production projects in the last 18 months without regrets. The constraint is that both ends must be TypeScript and ideally in the same monorepo. If you meet those constraints, tRPC is the most productive way to build internal APIs in 2026.

How should I version my API?

URL versioning (/api/v1/) for most projects because it is visible, debuggable, and trivially routable. Date-based versioning (Stripe-style) for APIs that evolve frequently without major redesigns. Always version from day one — adding versioning after launch is itself a breaking change. Support old versions for at least 12 months after deprecation.

What is the safest way to handle authentication for a SPA?

If your SPA is on the same domain as your API, use HttpOnly Secure SameSite=Lax cookies with CSRF tokens. If they are on different domains, use short-lived JWT access tokens (15 minutes) with refresh tokens. Never store JWTs in localStorage — XSS will exfiltrate them. The "JWT in localStorage" pattern is a security mistake that tutorials keep teaching.

How do I prevent breaking changes when evolving an API?

Three rules: additive changes (new optional fields, new endpoints) are safe and do not require a version bump; deprecate fields with the @deprecated directive (GraphQL) or Sunset header (REST) before removing them; run usage analytics so you know when a field is safe to delete. If your API has paying customers, support deprecated versions for at least 12-24 months.

Should I build a custom API gateway or use an off-the-shelf one?

Off-the-shelf, unless you have a very specific reason. Kong, Tyk, AWS API Gateway, Cloudflare API Shield, and Apigee all handle rate limiting, authentication, request transformation, and observability. Building your own is a multi-year project that distracts from your actual product. Custom gateways make sense for hyperscale companies (Netflix, Uber) and almost no one else.

Ship your API right the first time

API design is one of those areas where the difference between "good enough" and "actually good" compounds over years. A clean v1 saves you from rewriting v2 in panic. A versioning strategy saves your customer relationships. A proper authorization model saves you from data breaches. These are not optional polish — they are the structural integrity of your product.

I have spent five years building APIs for clients across Egypt, Saudi Arabia, the UAE, the UK, Switzerland, France, Germany, and Kuwait. The patterns I described in this article are the ones that survived production. If you are building a new SaaS, choosing between WordPress and Laravel, or launching an e-commerce platform, the API is your foundation. Get it right.

If you want a second pair of eyes on your API design before you ship — to catch the mistakes that take months to fix later — I offer free 30-minute design reviews. We will walk through your endpoints, your authentication, your versioning strategy, and your scaling plan, and I will tell you honestly what will hurt you in 18 months. Whether you are a solo founder or an agency, the right review at the right time pays for itself many times over. Book a free consultation here, or browse my backend and API services to see how we can work together. Ship the API your future self will thank you for.