api-endpoint-design

name	api-endpoint-design
description	REST API design standards for FanHub's Express backend. Use when creating or modifying API endpoints to ensure consistency.

FanHub API Design Standards

URL Conventions

• Use lowercase, hyphenated paths: /api/tv-shows, not /api/tvShows
• Use plural nouns for collections: /api/characters, not /api/character
• Use nested routes for relationships: /api/shows/:showId/episodes
• Version the API: /api/v1/...

HTTP Methods

Method	Use Case	Example
GET	Retrieve resource(s)	GET /api/characters
POST	Create new resource	POST /api/characters
PUT	Replace entire resource	PUT /api/characters/:id
PATCH	Partial update	PATCH /api/characters/:id
DELETE	Remove resource	DELETE /api/characters/:id

Response Format

All responses follow this structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Character name is required",
    "details": [...]
  }
}

Status Codes

• 200: Success (GET, PUT, PATCH)
• 201: Created (POST)
• 204: No Content (DELETE)
• 400: Bad Request (validation errors)
• 401: Unauthorized
• 404: Not Found
• 500: Internal Server Error

Endpoint Template

router.get('/characters', async (req, res, next) => {
  try {
    const { page = 1, limit = 20, show_id } = req.query;
    
    const characters = await CharacterService.list({
      page: parseInt(page),
      limit: parseInt(limit),
      showId: show_id ? parseInt(show_id) : undefined
    });
    
    res.json({
      success: true,
      data: characters.items,
      meta: {
        total: characters.total,
        page: characters.page,
        limit: characters.limit
      }
    });
  } catch (error) {
    next(error);
  }
});