API Design Best Practices: REST, GraphQL, and the Patterns That Scale

# Good
GET    /api/users          → List users
POST   /api/users          → Create a user
GET    /api/users/123      → Get a specific user
PUT    /api/users/123      → Replace a user
PATCH  /api/users/123      → Partially update a user
DELETE /api/users/123      → Delete a user

# Bad
GET    /api/getUsers
POST   /api/createUser
POST   /api/deleteUser/123
GET    /api/getUserById?id=123

# Nested — use when the child resource does not make sense without the parent
GET /api/users/123/orders          → Orders belonging to user 123

# Flat — use when the child resource has its own identity
GET /api/orders?user_id=123        → Orders filtered by user
GET /api/orders/456                → A specific order (regardless of user)

// Express.js example — proper status codes
app.get('/api/users/:id', async (req, res) => {
  try {
    const user = await db.users.findById(req.params.id);

    if (!user) {
      return res.status(404).json({
        error: 'NOT_FOUND',
        message: `User with id ${req.params.id} does not exist`,
      });
    }

    res.status(200).json({ data: user });
  } catch (err) {
    console.error('Error fetching user:', err);
    res.status(500).json({
      error: 'INTERNAL_SERVER_ERROR',
      message: 'An unexpected error occurred',
    });
  }
});

GET /api/v1/users
GET /api/v2/users

GET /api/users
Accept: application/vnd.myapi.v2+json

GET /api/products?page=2&limit=20

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  }
}

GET /api/products?cursor=eyJpZCI6MTAwfQ&limit=20

{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTIwfQ",
    "hasMore": true
  }
}

type User {
  id: ID!
  name: String!
  email: String!
  role: Role!
  orders(limit: Int = 10): [Order!]!
  addresses: [Address!]!
  createdAt: DateTime!
}

type Order {
  id: ID!
  total: Float!
  status: OrderStatus!
  items: [OrderItem!]!
  createdAt: DateTime!
}

enum Role {
  USER
  ADMIN
  MODERATOR
}

enum OrderStatus {
  PENDING
  PROCESSING
  SHIPPED
  DELIVERED
  CANCELLED
}

type Query {
  user(id: ID!): User
  users(page: Int, limit: Int): UserConnection!
  order(id: ID!): Order
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}

# Mobile app — minimal data
query {
  user(id: "123") {
    name
    avatarUrl
  }
}

# Admin dashboard — detailed data
query {
  user(id: "123") {
    name
    email
    role
    createdAt
    orders(limit: 5) {
      id
      total
      status
    }
    addresses {
      city
      state
    }
  }
}

// Node.js with Apollo Server
const resolvers = {
  Query: {
    user: async (_, { id }, context) => {
      return context.db.users.findById(id);
    },
    users: async (_, { page = 1, limit = 20 }, context) => {
      return context.db.users.findMany({ page, limit });
    },
  },
  User: {
    orders: async (parent, { limit }, context) => {
      return context.db.orders.findByUserId(parent.id, { limit });
    },
    addresses: async (parent, _, context) => {
      return context.db.addresses.findByUserId(parent.id);
    },
  },
  Mutation: {
    createUser: async (_, { input }, context) => {
      return context.db.users.create(input);
    },
  },
};

import DataLoader from 'dataloader';

// Create a loader that batches user IDs
const ordersByUserLoader = new DataLoader(async (userIds) => {
  // One query instead of N queries
  const orders = await db.orders.findByUserIds(userIds);

  // Return results in the same order as the input IDs
  return userIds.map(id => orders.filter(order => order.userId === id));
});

// In the resolver
const resolvers = {
  User: {
    orders: (parent) => ordersByUserLoader.load(parent.id),
  },
};

// Server — define your API
import { initTRPC } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.create();

export const appRouter = t.router({
  user: t.router({
    getById: t.procedure
      .input(z.object({ id: z.string() }))
      .query(async ({ input }) => {
        const user = await db.users.findById(input.id);
        if (!user) throw new TRPCError({ code: 'NOT_FOUND' });
        return user;
      }),

    create: t.procedure
      .input(z.object({
        name: z.string().min(2),
        email: z.string().email(),
      }))
      .mutation(async ({ input }) => {
        return db.users.create(input);
      }),
  }),
});

export type AppRouter = typeof appRouter;

// Client — fully typed, autocompletions everywhere
import { trpc } from '@/utils/trpc';

function UserProfile({ userId }: { userId: string }) {
  const { data, isLoading } = trpc.user.getById.useQuery({ id: userId });

  // TypeScript knows `data` has `name`, `email`, etc.
  // Autocomplete works. Type errors are caught at build time.
  return <div>{data?.name}</div>;
}

// Login endpoint
app.post('/api/auth/login', async (req, res) => {
  const { email, password } = req.body;
  const user = await verifyCredentials(email, password);

  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  const token = jwt.sign(
    { userId: user.id, role: user.role },
    process.env.JWT_SECRET,
    { expiresIn: '15m' }
  );

  const refreshToken = jwt.sign(
    { userId: user.id },
    process.env.REFRESH_SECRET,
    { expiresIn: '7d' }
  );

  // Set refresh token as httpOnly cookie
  res.cookie('refreshToken', refreshToken, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 7 * 24 * 60 * 60 * 1000,
  });

  res.json({ token });
});

// Auth middleware
function authenticate(req, res, next) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing token' });
  }

  try {
    const token = authHeader.split(' ')[1];
    const payload = jwt.verify(token, process.env.JWT_SECRET);
    req.user = payload;
    next();
  } catch {
    res.status(401).json({ error: 'Invalid or expired token' });
  }
}

import session from 'express-session';
import RedisStore from 'connect-redis';

app.use(session({
  store: new RedisStore({ client: redisClient }),
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: true,
    httpOnly: true,
    maxAge: 24 * 60 * 60 * 1000, // 24 hours
    sameSite: 'strict',
  },
}));

function authenticateApiKey(req, res, next) {
  const apiKey = req.headers['x-api-key'];
  if (!apiKey) return res.status(401).json({ error: 'Missing API key' });

  const client = await db.apiKeys.findByKey(apiKey);
  if (!client || client.revokedAt) {
    return res.status(401).json({ error: 'Invalid API key' });
  }

  req.client = client;
  next();
}

import rateLimit from 'express-rate-limit';

// Global rate limit
const globalLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // 100 requests per window
  standardHeaders: true, // Return rate limit info in headers
  message: {
    error: 'RATE_LIMIT_EXCEEDED',
    message: 'Too many requests, please try again later',
    retryAfter: 900, // seconds
  },
});

// Stricter limit for auth endpoints
const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 10,
  message: { error: 'Too many login attempts' },
});

app.use('/api/', globalLimiter);
app.use('/api/auth/', authLimiter);

RateLimit-Limit: 100
RateLimit-Remaining: 23
RateLimit-Reset: 1708200000

// Error response format
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      },
      {
        "field": "name",
        "message": "Must be at least 2 characters"
      }
    ]
  }
}

// Centralized error handler in Express
app.use((err, req, res, next) => {
  console.error(`[${req.method}] ${req.path}:`, err);

  if (err.name === 'ValidationError') {
    return res.status(400).json({
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Invalid request data',
        details: err.details,
      },
    });
  }

  if (err.name === 'UnauthorizedError') {
    return res.status(401).json({
      error: {
        code: 'UNAUTHORIZED',
        message: 'Authentication required',
      },
    });
  }

  // Default — never expose internal error details in production
  res.status(500).json({
    error: {
      code: 'INTERNAL_ERROR',
      message: process.env.NODE_ENV === 'production'
        ? 'An unexpected error occurred'
        : err.message,
    },
  });
});

openapi: 3.0.3
info:
  title: E-Commerce API
  version: 1.0.0
  description: API for managing products, orders, and users
paths:
  /api/v1/products:
    get:
      summary: List products
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of products
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'

import swaggerUi from 'swagger-ui-express';
import swaggerDocument from './openapi.json';

app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

# GET request
http GET localhost:3000/api/users

# POST request with JSON body
http POST localhost:3000/api/users name="Priya" email="[email protected]"

# With authentication
http GET localhost:3000/api/users Authorization:"Bearer token123"