api-patterns

NaoyaTakashima's avatarfrom NaoyaTakashima

REST API design patterns, authentication, and error handling for this SaaS application

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026
[API Helpers]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for REST API design, focusing on standardized authentication, robust error handling, and efficient data management for SaaS applications. It streamlines the development process by offering pre-defined patterns for JWT token structures, Zod-based request validation, and consistent response formats, ensuring high-quality and maintainable API architecture.

Use Cases

  • Implementing secure JWT-based authentication and middleware to protect sensitive SaaS endpoints.
  • Standardizing error response formats and HTTP status codes across a microservices architecture to improve frontend debugging.
  • Designing scalable pagination and rate-limiting strategies to optimize API performance and prevent resource abuse.
  • Enforcing strict data validation using Zod schemas to ensure request integrity and reduce server-side vulnerabilities.
nameapi-patterns
descriptionREST API design patterns, authentication, and error handling for this SaaS application
allowed-toolsRead, Grep, Glob

API Patterns

Authentication

JWT Token Structure

interface JWTPayload {
  sub: string;        // User ID
  email: string;
  role: 'user' | 'admin';
  iat: number;
  exp: number;
}

Auth Middleware

// Always use authMiddleware for protected routes
import { authMiddleware } from '@/middleware/auth';

router.get('/protected', authMiddleware, handler);

Error Handling

Standard Error Codes

Code HTTP Status Description
AUTH_REQUIRED 401 Missing or invalid token
FORBIDDEN 403 Insufficient permissions
NOT_FOUND 404 Resource not found
VALIDATION_ERROR 400 Invalid request body
RATE_LIMITED 429 Too many requests
INTERNAL_ERROR 500 Server error

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": { "field": "email" }
  }
}

Pagination

Request

GET /api/users?page=1&limit=20&sort=createdAt&order=desc

Response

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Rate Limiting

  • Authenticated: 1000 requests/hour
  • Unauthenticated: 100 requests/hour
  • Endpoint-specific limits in src/config/rateLimit.ts

Validation

Use Zod for all request validation:

import { z } from 'zod';

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  password: z.string().min(8),
});