Hola devs! En esta ocasión les traigo información muy valiosa, aquí hablaré sobre diseño de sistemas, en particular de APIs así que estoy seguro que te será útil, además utilizaré ejemplos reales poniendo como caso de uso para mis ejemplos a un sistema de logística.
Diseñar una API no solo significa que “funcione”, sino que sea clara, segura, escalable y fácil de mantener. En este artículo veremos buenas prácticas para lograrlo, con ejemplos aplicados a un sistema de logística: paquetes, envíos, transportistas y seguimiento de entregas.
1. Usa nombres de recursos (no acciones)
Una API REST representa recursos como packages, deliveries, drivers, y no acciones como get, fetch, query. Usa sustantivos, no verbos.
❌ GET /getPackageDetails/123
✅ GET /packages/123
2. Usa plural para tus recursos
Usa nombres en plural (/packages, /drivers) para representar colecciones, manteniendo consistencia en todo el sistema.
❌ GET /warehouse/45
✅ GET /warehouses/45
3. Versiona tu API desde el inicio
Versionar tu API evita romper integraciones cuando hagas mejoras. Usa el prefijo /v1, /v2, etc.
❌ GET /deliveries/v1/456
✅ GET /v1/deliveries/456
4. Aplica idempotencia
En operaciones críticas (crear entrega, registrar paquete) asegúrate de que puedan repetirse sin efectos secundarios.
❌ POST /deliveries puede crear múltiples envíos si se ejecuta varias veces
✅ POST /deliveries con header Idempotency-Key: abc123 evita duplicados
5. Emplea query parameters para búsquedas y filtros
Filtrar y buscar debe hacerse con parámetros, no creando nuevos endpoints.
✅ GET /packages?status=in_transit
✅ GET /drivers?region=north
6. Pagina colecciones grandes
Esto evita tiempos de carga largos y errores de rendimiento y seguridad.
❌ GET /packages devuelve miles o millones de paquetes
✅ GET /packages?page=2&pageSize=50 devuelve los resultados por bloques
7. Ordenar resultados
Permite que el cliente obtenga los resultados en el orden que necesite.
✅ GET /deliveries?sort_by=estimatedArrival
8. No mezclar recursos sin sentido
Cada endpoint debe estar bien enfocado: un recurso por URL.
❌ GET /packages/123?driver=45 devuelve miles o millones de paquetes
✅ GET /drivers/45 o GET /packages/123/driver
9. Representa relaciones jerárquicas correctamente
Muestra la relación entre paquete y conductor de forma explícita en la URL.
❌ POST /assignDriver?packageId=321&driverId=45
✅ POST /packages/123/drivers/45
10. Dale lugar a la seguridad
Protege tu sistema con políticas como "100 requests por minuto".
Las firmas HMAC (o JWT) son más seguras, especialmente en sistemas con múltiples actores como clientes, transportistas y operadores.
✅ Usa JWT en lugar de API Key: los tokens JWT están firmados digitalmente, pueden llevar datos como el rol, el ID del usuario o la expiración, y permiten validar peticiones sin necesidad de acceder a base de datos.
❌ API Keys planas → fáciles de filtrar, no contienen contexto del usuario
✅ JWT firmados → más seguros, autovalidables, ideales para servicios distribuidos
❌ Sin límites de requests → abusos y caídas, ataques DDoS
✅ Límites por IP, usuario, o clave de API → protegen tus recursos y aseguran calidad de servicio
En conclusión, como podrás haberte dado cuenta estimado dev, una buen API debe ser predecible, segura y confiable y todo esto sólo es posible con un buen diseño. Ya sabes que ser ingeniero de software no es sólo hacer CRUDS, hay todo una estructura que lo soporta y que debes aprender a implementar para que no seas un tipeador de código, sino un verdadero ingeniero de software o un desarrollador de software excelente y dejes de temer que una IA te quitará tu empleo 😉🐿️
Si esta entrada te ha gustado ya sabes qué hacer!
Créditos de imagen de portada: Basada en Foto de Kelly Sikkema en Unsplash