Introducción
Esta API REST permite gestionar recurso principal (por ejemplo, usuarios, pedidos, productos). Está diseñada para integrarse fácilmente con aplicaciones web, móviles y servicios de terceros.
Reemplaza este texto con una descripción corta de tu negocio, casos de uso principales y cualquier restricción importante (límites de rate, tamaños máximos, etc.).
Autenticación
La API utiliza autenticación basada en Bearer Token. Debes enviar el encabezado:
Authorization: Bearer <tu_token_aquí>
Puedes cambiar esto si usas API keys, JWT, OAuth2, etc. Explica cómo obtener el token y su tiempo de vida.
Recursos y endpoints
/users
Recurso para gestionar usuarios del sistema (crear, listar, actualizar, eliminar).
| Método | Ruta | Descripción | Parámetros | Respuesta (200) |
|---|---|---|---|---|
| GET | /users |
Lista todos los usuarios. |
query page (opcional) · número de página query limit (opcional) · tamaño de página |
JSON
[
{
"id": 1,
"name": "Juan Pérez",
"email": "juan@example.com"
}
]
|
| GET | /users/{id} |
Obtiene el detalle de un usuario por ID. | path id (requerido) · ID del usuario |
JSON
{
"id": 1,
"name": "Juan Pérez",
"email": "juan@example.com"
}
|
| POST | /users |
Crea un nuevo usuario. |
body (JSON)
{
"name": "Nuevo Usuario",
"email": "nuevo@example.com",
"password": "********"
}
|
JSON
{
"id": 2,
"name": "Nuevo Usuario",
"email": "nuevo@example.com"
}
|
| PUT | /users/{id} |
Actualiza un usuario existente. |
path id (requerido) body (JSON) · campos a actualizar |
JSON
{
"id": 1,
"name": "Nombre Actualizado",
"email": "nuevo-correo@example.com"
}
|
| DELETE | /users/{id} |
Elimina un usuario. | path id (requerido) |
JSON
{
"deleted": true
}
|
/products
Describe aquí tus endpoints de productos, pedidos, etc. Copia la tabla anterior y ajusta rutas, parámetros y ejemplos.
Manejo de errores
La API utiliza códigos de estado HTTP estándar. Algunos ejemplos:
| Código | Significado | Ejemplo de respuesta |
|---|---|---|
400 Bad Request |
Solicitud inválida (parámetros incorrectos, JSON mal formado). |
{
"error": "VALIDATION_ERROR",
"message": "El campo 'email' es obligatorio."
}
|
401 Unauthorized |
Token inválido o ausente. |
{
"error": "UNAUTHORIZED",
"message": "Token de acceso requerido."
}
|
404 Not Found |
Recurso no encontrado. |
{
"error": "NOT_FOUND",
"message": "Usuario no encontrado."
}
|
500 Internal Server Error |
Error inesperado en el servidor. |
{
"error": "SERVER_ERROR",
"message": "Ha ocurrido un error inesperado."
}
|
Ejemplos de uso
curl
curl -X GET "https://api.mi-dominio.com/v1/users" \
-H "Authorization: Bearer <tu_token>" \
-H "Content-Type: application/json"
JavaScript (fetch)
fetch("https://api.mi-dominio.com/v1/users", {
method: "GET",
headers: {
"Authorization": "Bearer <tu_token>",
"Content-Type": "application/json"
}
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));