# Api Design

> Design RESTful APIs following best practices

- Skill: `vinilana/api-design-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vinilana/api-design-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vinilana/api-design-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: vinilana (https://skillmd.com/u/vinilana)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/vinilana/api-design-2

---


# API Design

## When to Use
Activate this skill when designing new API endpoints or reviewing existing ones. It ensures RESTful conventions, consistent response shapes, and proper HTTP semantics.

## Instructions

1. **Follow existing conventions**:
   - Base path: `/api/` prefix for all endpoints.
   - Resource naming: plural nouns (`/api/franchises`, not `/api/franchise`).
   - Route constants: Define paths in `packages/shared/src/constants.ts` under `API_ROUTES`.
2. **HTTP methods**:
   - `GET` — Read (list or single resource). Never mutate state.
   - `POST` — Create a new resource. Return 201 with created entity.
   - `PUT` — Full update of a resource.
   - `PATCH` — Partial update of a resource.
   - `DELETE` — Remove a resource.
3. **Response envelopes**:
   - Success: `ApiResponse<T>` — `{ data: T, message?: string }`
   - Error: `ApiErrorResponse` — `{ error: string, message?: string }`
4. **Status codes**:
   - `200` — Successful read or update
   - `201` — Successful creation
   - `400` — Validation error (missing required fields, invalid data)
   - `401` — Missing or invalid authentication token
   - `404` — Resource not found
   - `500` — Internal server error
5. **Query parameters**:
   - `?search=term` — Full-text search across relevant fields
   - `?page=1&limit=20` — Pagination (future)
   - `?status=active` — Filtering (future)
6. **Input validation**:
   - NestJS: Use `class-validator` decorators on DTO classes.
   - Express: Manual validation checking required fields before processing.
   - Always validate: `name` (required), `owner_name` (required), `email` (required, format).
7. **Legacy policy**: New API endpoints must be designed for NestJS only. The Express.js API is frozen (legacy) and should not receive new endpoints or features. Only critical bug fixes are permitted in the Express backend. Existing dual-implementation endpoints remain as-is, but new work targets NestJS exclusively.

## Examples

**Endpoint specification:**

```
POST /api/franchises
Authorization: Bearer <token>
Content-Type: application/json

Request:
{
  "name": "Franchise São Paulo",
  "ownerName": "Maria Silva",
  "email": "maria@example.com",
  "phone": "(11) 99999-0000",
  "city": "São Paulo",
  "state": "SP",
  "status": "pending"
}

Response (201):
{
  "data": {
    "id": 11,
    "name": "Franchise São Paulo",
    "ownerName": "Maria Silva",
    "email": "maria@example.com",
    "phone": "(11) 99999-0000",
    "address": null,
    "city": "São Paulo",
    "state": "SP",
    "status": "pending",
    "createdAt": "2026-03-02T12:00:00.000Z",
    "updatedAt": "2026-03-02T12:00:00.000Z"
  }
}

Response (400):
{
  "error": "Validation failed",
  "message": "name, ownerName, and email are required"
}
```