hello-api

API-related code must follow the specifications below.

Before Coding

Determine the resource model and endpoint contract first, then write code.

RESTful Design

• Resource naming: plural nouns /users, nested /users/:id/posts
• HTTP method semantics: GET to read, POST to create, PUT for full update, PATCH for partial update, DELETE to delete
• Accurate status codes: 200 success, 201 created, 204 no content, 400 bad request, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict, 422 validation failed, 500 server error

Request Validation

• Input validation at the controller layer, using a schema validation library (zod, joi, ajv)
• Validate type, range, format, and required fields
• File uploads must limit size and type
• Request body size limit

Response Format

• Unified success response:{ data, meta? }
• Unified error response:{ error: { code, message, details? } }
• List endpoints must be paginated:?page=1&limit=20 or cursor-based
• Support sorting:?sort=created_at&order=desc
• Filter parameter whitelist

Versioning and Protection

• API versioning: URL prefix /v1/ or header
• Rate limiting protection: by IP/user/API key
• Timeout settings: set timeouts for all external calls
• CORS: explicitly allowed origins, do not use *

Delivery Checklist

• Status codes accurately reflect the operation result
• All inputs have been validated
• List endpoints have pagination
• Error response format is unified
• Rate limiting protection is in place