Convenciones URL, métodos y errores: API predecible y estandarizada

Última edición:

Diana Romanova

—

Junio 25, 2025

Convenciones URL, métodos, errores ('GET', 'POST', 'PUT', 'DELETE')

Una API fiable y comprensible comienza con reglas claras para la construcción de interfaces. Nos adherimos a las mejores prácticas de NAT para que cada desarrollador sepa qué esperar: la estructura de la URL es lógica, los métodos coinciden con la acción y los errores son fáciles de interpretar.

Esto reduce el umbral de entrada, simplifica las integraciones y permite escalar el sistema sin caos.

Convenciones de métodos URL y HTTP

Método	Asignación	Consulta de ejemplo
`GET`	Obtener recurso	`GET /users/42`
`POST`	Creación de un nuevo recurso	`POST /users`
`PUT`	Actualización completa del recurso	`PUT /users/42`
`PATCH`	Actualización parcial del recurso (ops.) `PATCH /users/42`
`DELETE`	Eliminar recurso	`DELETE /users/42`

Se utilizan sustantivos en plural ('/users ', '/devices', '/games ')

Las entidades anidadas se describen como jerarquía ('/users/42/sessions')
Todas las solicitudes pasan a través de HTTPS

Estándares de manejo de errores

Código	Valor	Ejemplo de mensaje
`400`	Consulta incorrecta	`Missing required field: email`
`401`	neavtorizovan	`Invalid token or expired session`
`403`	Acceso prohibido	`Access denied to resource`
`404`	No encontrado	`User with ID 42 not found`
`409`	Conflicto (por ejemplo, duplicación)	`Email already in use`
`422`	Error de validación	`Field 'age' must be a number`
`500`	Error interno del servidor	`Unexpected exception, contact support`

Estructura de respuesta de error:

json
{
"error": {
"code": 400,   "message": "Missing required field: email",   "details": {...}
}
}

Beneficios para desarrolladores

Comprensión rápida de la lógica de la API sin necesidad de documentación adicional

Enfoque unificado para todos los módulos y entidades
Fácil depuración y lógica gracias a los códigos y formatos estándar
Compatibilidad con OpenAPI/Swagger, Postman, generación automática SDK
Simplificación de soporte, pruebas y CI/CD

Donde es especialmente importante

Plataformas con API abiertas o asociadas

Proyectos con varios equipos de desarrollo
Arquitectura de microservicios o enfoque API-first
Sistemas con un gran número de entidades e interacciones

Las convenciones únicas hacen que la API sea confiable, comprensible y fácil de usar. Nos apegamos a las mejores prácticas NAT para que cada integración se lleve a cabo rápidamente, sin malentendidos y con la máxima previsibilidad.