Referencia API
Esta sección proporciona una referencia completa de la API disponible.
Introducción
La API está diseñada para ser simple y fácil de usar. Todos los endpoints siguen las mejores prácticas REST y devuelven respuestas en formato JSON.
URL Base
https://api.ejemplo.com/v1Autenticación
La mayoría de los endpoints requieren autenticación mediante tokens Bearer.
Obtener un Token
POST /auth/login
Content-Type: application/json
{
"email": "usuario@ejemplo.com",
"password": "tu-contraseña"
}Respuesta:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"user": {
"id": "123",
"email": "usuario@ejemplo.com",
"name": "Usuario"
}
}Usar el Token
Incluye el token en el header de tus peticiones:
Authorization: Bearer tu-token-aquiEndpoints Principales
Usuarios
GET /users
Obtiene la lista de usuarios.
Parámetros de Query:
| Parámetro | Tipo | Descripción |
|---|---|---|
page | number | Número de página (por defecto: 1) |
limit | number | Elementos por página (por defecto: 10) |
search | string | Término de búsqueda |
Ejemplo de Petición:
curl -X GET "https://api.ejemplo.com/v1/users?page=1&limit=10" \
-H "Authorization: Bearer tu-token"Respuesta:
{
"data": [
{
"id": "1",
"name": "Juan Pérez",
"email": "juan@ejemplo.com",
"createdAt": "2025-01-01T00:00:00Z"
}
],
"pagination": {
"total": 100,
"page": 1,
"limit": 10,
"pages": 10
}
}GET /users/:id
Obtiene un usuario por ID.
Parámetros de URL:
| Parámetro | Tipo | Descripción |
|---|---|---|
id | string | ID del usuario |
Ejemplo:
curl -X GET "https://api.ejemplo.com/v1/users/123" \
-H "Authorization: Bearer tu-token"POST /users
Crea un nuevo usuario.
Body:
{
"name": "María García",
"email": "maria@ejemplo.com",
"password": "contraseña-segura"
}Respuesta:
{
"id": "124",
"name": "María García",
"email": "maria@ejemplo.com",
"createdAt": "2025-11-22T10:00:00Z"
}PUT /users/:id
Actualiza un usuario existente.
Body:
{
"name": "María García Actualizado",
"email": "maria.nueva@ejemplo.com"
}DELETE /users/:id
Elimina un usuario.
Respuesta:
{
"message": "Usuario eliminado exitosamente"
}Códigos de Estado
La API usa los siguientes códigos de estado HTTP:
| Código | Significado |
|---|---|
200 | OK - La petición fue exitosa |
201 | Created - Recurso creado exitosamente |
400 | Bad Request - La petición es inválida |
401 | Unauthorized - Autenticación requerida |
403 | Forbidden - No tienes permisos |
404 | Not Found - Recurso no encontrado |
500 | Internal Server Error - Error del servidor |
Errores
Cuando ocurre un error, la API devuelve un objeto con el siguiente formato:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Los datos proporcionados son inválidos",
"details": [
{
"field": "email",
"message": "El email es requerido"
}
]
}
}Códigos de Error Comunes
| Código | Descripción |
|---|---|
VALIDATION_ERROR | Error de validación de datos |
AUTH_ERROR | Error de autenticación |
NOT_FOUND | Recurso no encontrado |
PERMISSION_DENIED | Permisos insuficientes |
RATE_LIMIT_EXCEEDED | Límite de tasa excedido |
Límites de Tasa
La API tiene límites de tasa para prevenir abuso:
- Autenticado: 1000 peticiones por hora
- No autenticado: 100 peticiones por hora
Los headers de respuesta incluyen información sobre tu límite:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1637664000Versionado
La API usa versionado en la URL. La versión actual es v1.
https://api.ejemplo.com/v1/usersAviso de Deprecación
Las versiones antiguas se mantendrán durante 6 meses después de que se lance una nueva versión.
Webhooks
Puedes configurar webhooks para recibir notificaciones de eventos.
Eventos Disponibles
user.created- Usuario creadouser.updated- Usuario actualizadouser.deleted- Usuario eliminado
Configurar un Webhook
POST /webhooks
Content-Type: application/json
{
"url": "https://tu-sitio.com/webhook",
"events": ["user.created", "user.updated"],
"secret": "tu-secreto-para-verificar-firma"
}SDKs
Ofrecemos SDKs oficiales para varios lenguajes: