¿Qué hace Revisión de Diseño de API?
Resumen
Evalúa una API desde el lado del cliente: nombres predecibles, códigos de estado honestos, un solo formato de error, reintentos seguros y sin cambios disruptivos sorpresa. Cada hallazgo apunta a una ruta concreta y muestra el diseño corregido.
Método
- Inventario. Lista cada endpoint como
METHOD /path → códigos de estado → forma de solicitud/respuesta. Lee rutas, controladores, archivos OpenAPI y DTOs. - Revisa cada endpoint según las reglas a continuación.
- Revisa la API como un todo: la coherencia entre endpoints es más importante que cualquier decisión individual.
- Cambios: si se revisa un diff, compara los contratos antiguos y nuevos, y marca todo lo que rompa a los clientes existentes.
- Informe usando el contrato a continuación.
Reglas
| Área | Regla |
|---|---|
| Recursos | Sustantivos en plural, sin verbos: POST /orders, no /createOrder. Anida solo para propiedad verdadera: /users/{id}/orders. |
| Métodos | GET lee y es seguro. POST crea. PUT reemplaza. PATCH actualiza parcialmente. DELETE elimina. Nunca cambiar estado en GET. |
| Códigos de estado | 200 OK, 201 Creado (+ Location), 204 Sin Contenido, 400 entrada inválida, 401 no autenticado, 403 no permitido, 404 no encontrado, 409 conflicto, 422 validación, 429 límite de velocidad, 5xx solo para fallos del servidor. Nunca 200 con {"error": ...}. |
| Errores | Un solo formato en todas partes, ej. RFC 9457: { "type", "title", "status", "detail", "errors": [{ "field", "message" }] }. Sin trazas de pila ni SQL en las respuestas. |
| Nombres | Un solo tipo de mayúsculas/minúsculas en los campos JSON (camelCase o snake_case), IDs consistentes, marcas de tiempo ISO 8601 UTC, dinero como unidades enteras menores o cadena decimal más moneda. |
| Colecciones | Pagina cada lista (cursor preferido para datos grandes o cambiantes), limita el tamaño de página, devuelve cursor o enlaces siguientes. Filtrado y ordenación mediante parámetros de consulta. |
| Idempotencia | POSTs repetidos que crean pagos, pedidos o correos electrónicos aceptan una Idempotency-Key. PUT y DELETE son idempotentes por diseño. |
| Versionado | Una estrategia clara (/v1 en ruta o cabecera). Los cambios disruptivos van a una nueva versión. |
| Cambios disruptivos | Eliminar o renombrar campos, cambiar tipos, hacer obligatoria una entrada opcional, cambiar códigos de estado o formato de error, endurecer validación. |
| Seguridad | Autenticación en cada ruta no pública, comprobaciones de propiedad a nivel de objeto, límites de velocidad en rutas de autenticación y costosas, sin datos sensibles en URLs. |
| Rendimiento | Sin respuestas ilimitadas, soportar fields o respuestas dispersas para objetos pesados, ETag o Cache-Control para GETs almacenables en caché. |
Contrato de salida
Comienza con: N endpoints revisados, M hallazgos (X disruptivos). Luego, el de mayor impacto primero:
### [Disruptivo | Alto | Medio | Bajo] Título
- Endpoint: METHOD /path (archivo:línea)
- Problema: lo que experimenta un cliente
- Solución: la ruta, código de estado o forma JSON corregidos
Finaliza con un breve Resumen de coherencia (mayúsculas/minúsculas, formato de error, paginación, versionado: coherente o no) y, al diseñar desde cero, la tabla de endpoints propuesta.
Errores comunes
- Revisar endpoints uno por uno y no notar que dos de ellos discrepan en mayúsculas/minúsculas o formato de error.
- Recomendar un rediseño cuando una adición compatible hacia atrás sería suficiente.
- Llamar seguro a un cambio porque el código del servidor aún funciona: verifica qué envían y esperan los clientes existentes.
- Usar 500 para errores de validación o 404 para fallos de permiso sin decidir deliberadamente.
Creado por Wageesha Tripathi · LinkedIn · Email · Más habilidades