REST API Design Best Practices: Versioning, Error Handling, Rate Limiting & OpenAPI

# ❌ BAD — RPC-style, not REST
POST /getUser
POST /createNewBlogPost
GET  /deleteComment?id=5

# ✅ GOOD — Resource-oriented
GET    /users/{id}
POST   /posts
DELETE /posts/{postId}/comments/{commentId}

// GET /posts?page=2&limit=10
{
  "data": [
    { "id": "post_abc123", "title": "...", "excerpt": "..." },
    { "id": "post_def456", "title": "...", "excerpt": "..." }
  ],
  "meta": {
    "page": 2,
    "limit": 10,
    "total": 847,
    "totalPages": 85
  },
  "links": {
    "self": "/posts?page=2&limit=10",
    "next": "/posts?page=3&limit=10",
    "prev": "/posts?page=1&limit=10",
    "first": "/posts?page=1&limit=10",
    "last": "/posts?page=85&limit=10"
  }
}

// 422 Unprocessable Entity
{
  "type": "https://api.bipinbaral.com.np/problems/validation-error",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request body contains invalid fields",
  "instance": "/posts",
  "errors": [
    {
      "field": "title",
      "code": "TOO_SHORT",
      "message": "Title must be at least 5 characters",
      "received": "Hi"
    },
    {
      "field": "category",
      "code": "INVALID_VALUE",
      "message": "Category must be one of: tech, devops, ai, security",
      "received": "random-stuff"
    }
  ]
}

/api/v1/posts
/api/v2/posts    ← Breaking changes go here

GET /api/posts
API-Version: 2026-08-01

Accept: application/vnd.bipinapi.v2+json

// Using express-rate-limit + Redis
import rateLimit from "express-rate-limit";
import RedisStore from "rate-limit-redis";
import { Redis } from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);

// Different limits for different endpoints
export const standardRateLimit = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,                   // 100 requests per window
  standardHeaders: "draft-7",
  legacyHeaders: false,
  store: new RedisStore({ sendCommand: (...args) => redis.call(...args) }),
  keyGenerator: (req) => req.user?.id ?? req.ip, // Per-user limiting for authenticated
  handler: (req, res) => {
    res.status(429).json({
      type: "https://api.example.com/problems/rate-limit-exceeded",
      title: "Rate Limit Exceeded",
      status: 429,
      detail: "Too many requests. Please wait before retrying.",
      retryAfter: res.getHeader("Retry-After"),
    });
  },
});

export const authRateLimit = rateLimit({
  windowMs: 15 * 60 * 1000,
  max: 10, // Only 10 login attempts per 15 minutes
  store: new RedisStore({ sendCommand: (...args) => redis.call(...args) }),
});

RateLimit-Limit: 100
RateLimit-Remaining: 43
RateLimit-Reset: 1724234400    ← Unix timestamp when window resets
Retry-After: 847               ← Seconds to wait (only on 429)

// Cursor pagination — efficient even for millions of rows
app.get("/api/posts", async (req, res) => {
  const limit = Math.min(parseInt(req.query.limit as string) || 10, 100);
  const cursor = req.query.cursor as string | undefined;

  let query = db
    .selectFrom("posts")
    .select(["id", "title", "excerpt", "published_at"])
    .where("status", "=", "published")
    .orderBy("published_at", "desc")
    .orderBy("id", "desc") // Tiebreaker for stable sort
    .limit(limit + 1); // Fetch 1 extra to know if there's a next page

  if (cursor) {
    const { date, id } = decodeCursor(cursor);
    query = query.where((eb) =>
      eb.or([
        eb("published_at", "<", date),
        eb.and([eb("published_at", "=", date), eb("id", "<", id)]),
      ])
    );
  }

  const rows = await query.execute();
  const hasNextPage = rows.length > limit;
  const items = hasNextPage ? rows.slice(0, limit) : rows;

  const nextCursor =
    hasNextPage && items.length > 0
      ? encodeCursor({ date: items.at(-1)!.published_at, id: items.at(-1)!.id })
      : null;

  res.json({
    data: items,
    meta: { limit, hasNextPage },
    links: {
      next: nextCursor ? `/api/posts?cursor=${nextCursor}&limit=${limit}` : null,
    },
  });
});

// With NestJS + @nestjs/swagger
import { ApiProperty, ApiResponse, ApiOperation } from "@nestjs/swagger";

export class CreatePostDto {
  @ApiProperty({ example: "My Tech Article", minLength: 5, maxLength: 200 })
  title: string;

  @ApiProperty({ example: "tech", enum: ["tech", "devops", "ai", "security"] })
  category: string;
}

@Controller("posts")
@ApiTags("Posts")
export class PostsController {
  @Post()
  @ApiOperation({ summary: "Create a new blog post" })
  @ApiResponse({ status: 201, description: "Post created successfully", type: PostDto })
  @ApiResponse({ status: 422, description: "Validation failed", type: ProblemDetailDto })
  create(@Body() dto: CreatePostDto) {
    return this.postsService.create(dto);
  }
}