rest-api

REST API Design

Instructions

1. Assess the API need: CRUD operations, complex queries, or real-time data.
2. Follow REST conventions:
   • Use nouns for resources, not verbs
   • Proper HTTP methods and status codes
   • Consistent naming conventions
   • HATEOAS where appropriate
3. Provide complete examples: Include routes, handlers, and response schemas.
4. Guide on best practices: Versioning, pagination, filtering, error handling.

HTTP Methods

Method	Purpose	Idempotent	Safe
GET	Retrieve resource(s)	Yes	Yes
POST	Create resource	No	No
PUT	Replace resource	Yes	No
PATCH	Partial update	No	No
DELETE	Remove resource	Yes	No

Resource Naming

# Good - Nouns, plural
GET    /users
GET    /users/:id
POST   /users
PUT    /users/:id
PATCH  /users/:id
DELETE /users/:id

# Nested resources
GET    /users/:userId/posts
GET    /users/:userId/posts/:postId
POST   /users/:userId/posts

# Bad - Verbs, actions in URL
GET    /getUsers
POST   /createUser
GET    /getUserById/:id

Status Codes

Success (2xx)

// 200 OK - Successful GET, PUT, PATCH
res.status(200).json({ data: user });

// 201 Created - Successful POST
res.status(201).json({ data: newUser });

// 204 No Content - Successful DELETE
res.status(204).send();

Client Errors (4xx)

// 400 Bad Request - Invalid input
res.status(400).json({
  error: {
    code: 'VALIDATION_ERROR',
    message: 'Invalid request body',
    details: [
      { field: 'email', message: 'Must be a valid email' }
    ]
  }
});

// 401 Unauthorized - Not authenticated
res.status(401).json({
  error: {
    code: 'UNAUTHORIZED',
    message: 'Authentication required'
  }
});

// 403 Forbidden - Authenticated but not authorized
res.status(403).json({
  error: {
    code: 'FORBIDDEN',
    message: 'You do not have permission to access this resource'
  }
});

// 404 Not Found
res.status(404).json({
  error: {
    code: 'NOT_FOUND',
    message: 'User not found'
  }
});

// 409 Conflict - Resource already exists
res.status(409).json({
  error: {
    code: 'CONFLICT',
    message: 'Email already registered'
  }
});

// 422 Unprocessable Entity - Semantic errors
res.status(422).json({
  error: {
    code: 'UNPROCESSABLE_ENTITY',
    message: 'Cannot delete user with active subscriptions'
  }
});

// 429 Too Many Requests - Rate limiting
res.status(429).json({
  error: {
    code: 'RATE_LIMITED',
    message: 'Too many requests',
    retryAfter: 60
  }
});