URL, métodos y errores de API

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

Última actualización:
Stanislav Anisimov
Convenciones URL, métodos, errores ('GET', 'POST', 'PUT', 'DELETE')
Click to expand / collapse

Una API confiable 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étodoAsignaciónConsulta 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ódigoValorEjemplo 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 abierta o de afiliados

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 conveniente. 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.

Temas populares

Temas principales