Api Design | Skills Pool
Api Design REST API design conventions for Vera Sesiom. Endpoint naming, request/response formats, error handling, and versioning. Trigger: When designing API endpoints, handling errors, or establishing API conventions.
asolis87 0 estrellas 30 mar 2026 Ocupación Categorías Backend Contenido de la habilidad
When to Use
Designing new API endpoints
Defining request/response formats
Implementing error handling
Setting up API versioning
Reviewing API contracts
Critical Rules
RESTful naming — resources are nouns, plural, lowercaseConsistent response format — always { data, meta?, error? }HTTP status codes MUST be correct — no 200 for errorsAPI versioning from day one — /api/v1/Validation at the boundary — Zod schemas for all inputsPagination for all list endpoints — no unbounded queriesISO 8601 for dates — 2024-01-15T10:30:00Z
URL Conventions
Structure
Instalación rápida
Api Design npx skills add asolis87/vera-sesiom-skills
estrellas 0
Actualizado 30 mar 2026
Ocupación /api/v{version}/{resource}
/api/v{version}/{resource}/{id}
/api/v{version}/{resource}/{id}/{sub-resource}
Examples GET /api/v1/users # List users
POST /api/v1/users # Create user
GET /api/v1/users/:id # Get user by ID
PUT /api/v1/users/:id # Full update
PATCH /api/v1/users/:id # Partial update
DELETE /api/v1/users/:id # Delete user
GET /api/v1/users/:id/orders # List user's orders
Naming Rules Rule Good Bad Plural nouns /users/user, /getUsersLowercase /users/UsersKebab-case for multi-word /order-items/orderItems, /order_itemsNo verbs in URLs /users (POST)/createUserNesting max 2 levels /users/:id/orders/users/:id/orders/:oid/items/:iid
Success Response // Single resource
{
"data": {
"id": "123",
"name": "John Doe",
"email": "[email protected] ",
"createdAt": "2024-01-15T10:30:00Z"
}
}
// List (paginated)
{
"data": [
{ "id": "1", "name": "Alice" },
{ "id": "2", "name": "Bob" }
],
"meta": {
"total": 50,
"page": 1,
"perPage": 20,
"totalPages": 3
}
}
// Empty list
{
"data": [],
"meta": {
"total": 0,
"page": 1,
"perPage": 20,
"totalPages": 0
}
}
Error Response {
"error": {
"code": "USER_NOT_FOUND",
"message": "User with id \"123\" not found",
"details": []
}
}
// Validation error
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request body",
"details": [
{ "field": "email", "message": "Invalid email format" },
{ "field": "name", "message": "Name is required" }
]
}
}
HTTP Status Codes
Success Code When 200 OKGET, PUT, PATCH success 201 CreatedPOST success (resource created) 204 No ContentDELETE success
Client Errors Code When 400 Bad RequestValidation error, malformed request 401 UnauthorizedMissing or invalid authentication 403 ForbiddenAuthenticated but not authorized 404 Not FoundResource doesn't exist 409 ConflictDuplicate resource, state conflict 422 Unprocessable EntityValid syntax but semantic error
Server Errors Code When 500 Internal Server ErrorUnhandled server error 502 Bad GatewayUpstream service failure 503 Service UnavailableServer temporarily down
Query Parameters GET /api/v1/users?page=2&perPage=20&sort=createdAt&order=desc
Parameter Default Max Description page1 - Page number perPage20 100 Items per page sortcreatedAt- Sort field orderdesc- asc or desc
Filtering GET /api/v1/users?role=admin&isActive=true&search=john
Authentication
Authorization: Bearer <jwt-token>
Protected vs Public Endpoints // Public
router.post('/api/v1/auth/login', ...)
router.post('/api/v1/auth/register', ...)
// Protected (requires auth middleware)
router.get('/api/v1/users', authMiddleware, ...)
router.post('/api/v1/orders', authMiddleware, ...)
Versioning Strategy
URL-based versioning : /api/v1/, /api/v2/Only bump major version for breaking changes
Maintain previous version for minimum 6 months after deprecation
Use Deprecation header for sunsetting endpoints
Deprecation: true
Sunset: Sat, 01 Jul 2025 00:00:00 GMT
Link: </api/v2/users>; rel="successor-version"
Anti-Patterns Anti-Pattern Fix Return 200 with error in body Use proper HTTP status codes Unbounded list queries Always paginate Expose internal IDs (auto-increment) Use UUIDs Return domain entities directly Map to DTOs/response format Different error formats per endpoint Use consistent error format Verbs in URLs (/getUser) Use HTTP methods + nouns
02
Critical Rules
Backend
Acp Router Route plain-language requests for Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI, Qwen, Kiro, Kimi, iFlow, Factory Droid, Kilocode, or ACP harness work into either OpenClaw ACP runtime sessions or direct acpx-driven sessions ("telephone game" flow). For coding-agent thread requests, read this skill first, then use only `sessions_spawn` for thread creation.