Agent skill

api-design-restful

RESTful API design patterns, error handling, and documentation

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/autohandai/community-skills/tree/main/api-design-restful

SKILL.md

RESTful API Design

Core Principles

  1. Resource-Oriented - URLs represent nouns, not verbs
  2. Stateless - Each request contains all necessary information
  3. Consistent - Use standard HTTP methods and status codes
  4. Versioned - Support API evolution without breaking clients

URL Structure

# Collection resources
GET    /api/v1/users           # List users
POST   /api/v1/users           # Create user

# Individual resources
GET    /api/v1/users/:id       # Get user
PUT    /api/v1/users/:id       # Replace user
PATCH  /api/v1/users/:id       # Update user
DELETE /api/v1/users/:id       # Delete user

# Nested resources
GET    /api/v1/users/:id/posts # User's posts
POST   /api/v1/users/:id/posts # Create post for user

# Filtering, sorting, pagination
GET    /api/v1/users?status=active&sort=-createdAt&page=2&limit=20

Response Structure

Success Response

typescript
interface SuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    page?: number;
    limit?: number;
    total?: number;
    totalPages?: number;
  };
}

// Example
{
  "success": true,
  "data": { "id": "123", "name": "John" },
  "meta": { "requestId": "abc-123" }
}

Error Response

typescript
interface ErrorResponse {
  success: false;
  error: {
    code: string;        // Machine-readable code
    message: string;     // Human-readable message
    details?: unknown;   // Field-level errors
  };
}

// Example
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "email": "Invalid email format",
      "age": "Must be a positive number"
    }
  }
}

HTTP Status Codes

typescript
// Success
200 OK              // Successful GET, PUT, PATCH
201 Created         // Successful POST
204 No Content      // Successful DELETE

// Client Errors
400 Bad Request     // Validation errors
401 Unauthorized    // Missing/invalid auth
403 Forbidden       // Insufficient permissions
404 Not Found       // Resource doesn't exist
409 Conflict        // Duplicate/state conflict
422 Unprocessable   // Semantic errors
429 Too Many Reqs   // Rate limited

// Server Errors
500 Internal Error  // Unexpected server error
503 Unavailable     // Service temporarily down

Express.js Implementation

typescript
import express from 'express';

const app = express();

// Async handler wrapper
const asyncHandler = (fn: RequestHandler) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

// Controller
const getUsers = asyncHandler(async (req, res) => {
  const { page = 1, limit = 20, status } = req.query;
  const { users, total } = await userService.findAll({ page, limit, status });

  res.json({
    success: true,
    data: users,
    meta: { page, limit, total, totalPages: Math.ceil(total / limit) }
  });
});

// Error handler middleware
app.use((err, req, res, next) => {
  const status = err.status || 500;
  res.status(status).json({
    success: false,
    error: {
      code: err.code || 'INTERNAL_ERROR',
      message: err.message || 'Something went wrong',
      ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
    }
  });
});

Validation with Zod

typescript
import { z } from 'zod';

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  role: z.enum(['user', 'admin']).default('user'),
});

// Middleware
const validate = (schema: z.ZodSchema) => (req, res, next) => {
  const result = schema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Invalid request body',
        details: result.error.flatten().fieldErrors
      }
    });
  }
  req.body = result.data;
  next();
};

app.post('/users', validate(createUserSchema), createUser);

Authentication

typescript
// JWT middleware
const authenticate = asyncHandler(async (req, res, next) => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) {
    throw new ApiError(401, 'UNAUTHORIZED', 'Missing auth token');
  }

  const payload = await verifyToken(token);
  req.user = payload;
  next();
});

// Role-based authorization
const authorize = (...roles: string[]) => (req, res, next) => {
  if (!roles.includes(req.user.role)) {
    throw new ApiError(403, 'FORBIDDEN', 'Insufficient permissions');
  }
  next();
};

app.delete('/users/:id', authenticate, authorize('admin'), deleteUser);

Rate Limiting

typescript
import rateLimit from 'express-rate-limit';

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,
  standardHeaders: true,
  legacyHeaders: false,
  handler: (req, res) => {
    res.status(429).json({
      success: false,
      error: {
        code: 'RATE_LIMITED',
        message: 'Too many requests, please try again later'
      }
    });
  }
});

app.use('/api/', limiter);

Best Practices

  1. Use plural nouns for resources (/users not /user)
  2. Version your API from day one (/api/v1/)
  3. Return appropriate status codes for every response
  4. Include request IDs in responses for debugging
  5. Document with OpenAPI/Swagger specification
  6. Implement pagination for list endpoints
  7. Use consistent error format across all endpoints
  8. Log all requests with correlation IDs

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

autohandai/community-skills

mapping-mitre-attack-techniques

Maps observed adversary behaviors, security alerts, and detection rules to MITRE ATT&CK techniques and sub-techniques to quantify detection coverage and guide control prioritization. Use when building an ATT&CK-based coverage heatmap, tagging SIEM alerts with technique IDs, aligning security controls to adversary playbooks, or reporting threat exposure to executives. Activates for requests involving ATT&CK Navigator, Sigma rules, MITRE D3FEND, or coverage gap analysis.

0 0
Explore
autohandai/community-skills

hunting-for-spearphishing-indicators

Hunt for spearphishing campaign indicators across email logs, endpoint telemetry, and network data to detect targeted email attacks.

0 0
Explore
autohandai/community-skills

analyzing-malicious-url-with-urlscan

URLScan.io is a free service for scanning and analyzing suspicious URLs. It captures screenshots, DOM content, HTTP transactions, JavaScript behavior, and network connections of web pages in an isolat

0 0
Explore
autohandai/community-skills

implementing-zero-standing-privilege-with-cyberark

Deploy CyberArk Secure Cloud Access to eliminate standing privileges in hybrid and multi-cloud environments using just-in-time access with time, entitlement, and approval controls.

0 0
Explore
autohandai/community-skills

implementing-pam-for-database-access

Deploy privileged access management for database systems including Oracle, SQL Server, PostgreSQL, and MySQL. Covers session proxy configuration, credential vaulting, query auditing, dynamic credentia

0 0
Explore
autohandai/community-skills

detecting-t1003-credential-dumping-with-edr

Detect OS credential dumping techniques targeting LSASS memory, SAM database, NTDS.dit, and cached credentials using EDR telemetry, Sysmon process access monitoring, and Windows security event correlation.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results