api-design

What this skill does

When applied, it prepends a system prompt before your request is sent — no extra calls and no change to how you are billed beyond the added tokens.

---
name: api-design
description: Patrones de diseño REST API incluyendo nomenclatura de recursos, códigos de estado, paginación, filtrado, respuestas de error, versionado y rate limiting para APIs de producción.
origin: ECC
---

# Patrones de Diseño de API

Convenciones y buenas prácticas para diseñar APIs REST consistentes y amigables para desarrolladores.

## Cuándo Activar

- Diseñar nuevos endpoints de API
- Revisar contratos de API existentes
- Agregar paginación, filtrado u ordenamiento
- Implementar manejo de errores para APIs
- Planificar la estrategia de versionado de API
- Construir APIs públicas o para partners

## Diseño de Recursos

### Estructura de URL

```
# Los recursos son sustantivos, plural, minúsculas, kebab-case
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# Sub-recursos para relaciones
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# Acciones que no mapean a CRUD (usar verbos con moderación)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
```

### Reglas de Nomenclatura

```
# BIEN
/api/v1/team-members          # kebab-case para recursos de varias palabras
/api/v1/orders?status=active  # query params para filtrado
/api/v1/users/123/orders      # recursos anidados para pertenencia

# MAL
/api/v1/getUsers              # verbo en la URL
/api/v1/user                  # singular (usar plural)
/api/v1/team_members          # snake_case en URLs
/api/v1/users/123/getOrders   # verbo en recurso anidado
```

## Métodos HTTP y Códigos de Estado

### Semántica de Métodos

| Método | Idempotente | Seguro | Usar Para |
|--------|-----------|------|---------|
| GET | Sí | Sí | Recuperar recursos |
| POST | No | No | Crear recursos, disparar acciones |
| PUT | Sí | No | Reemplazo completo de un recurso |
| PATCH | No* | No | Actualización parcial de un recurso |
| DELETE | Sí | No | Eliminar un recurso |

Use this skill

{
  "model": "gpt-4o-mini",
  "skill": "imp-5ea92ae0-379b-4a06-a53a-b78ba0417ab4",
  "messages": [{ "role": "user", "content": "…" }]
}

More skills