api-endpoint-design

MSBart2 的头像作者 MSBart2

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

📖 中文导读:REST API design standards for FanHub's Express backend. Use when creating or modifying API endpoints to ensure consistency. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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);
  }
});