Si estás aprendiendo a diseñar APIs, hay ciertas prácticas que te...
Julián Campos@juliancamposes
11 views
Sep 11, 2025
~2 min read
Advertisement
1
Si estás aprendiendo a diseñar APIs, hay ciertas prácticas que te van a ahorrar muchísimos problemas.
Aplicarlas hará tus APIs:
✅ más predecibles
✅ más seguras
✅ más fáciles de mantener
Aquí te explico las 7 mejores prácticas de diseño de APIs 🧵👇
Aplicarlas hará tus APIs:
✅ más predecibles
✅ más seguras
✅ más fáciles de mantener
Aquí te explico las 7 mejores prácticas de diseño de APIs 🧵👇
2
1️⃣ Fundamentos REST
Un patrón para que sistemas hablen entre sí usando HTTP.
👉 Piensa en REST como una biblioteca:
Un solo acceso (entrada) Libros organizados por secciones
Un patrón para que sistemas hablen entre sí usando HTTP.
👉 Piensa en REST como una biblioteca:
Un solo acceso (entrada) Libros organizados por secciones
3
Así funcionan los endpoints:
🟢/items → lista de items
🟢/items/123 → un item específico
Métodos HTTP:
🧾GET = leer
✏️POST = crear
🔁PUT = actualizar
🗑️DELETE = borrar
🟢/items → lista de items
🟢/items/123 → un item específico
Métodos HTTP:
🧾GET = leer
✏️POST = crear
🔁PUT = actualizar
🗑️DELETE = borrar
4
2⃣ Manejo de errores
Los status codes deben ser claros.
❌ Mal: error genérico, sin contexto.
✅ Bien: indicar qué falló y por qué.
Un buen manejo de errores = APIs confiables.
Los status codes deben ser claros.
❌ Mal: error genérico, sin contexto.
✅ Bien: indicar qué falló y por qué.
Un buen manejo de errores = APIs confiables.
5
Ejemplo:
404 Not Found → recurso no existe
400 Bad Request → parámetros incorrectos
500 Internal Server Error → error del server
404 Not Found → recurso no existe
400 Bad Request → parámetros incorrectos
500 Internal Server Error → error del server
6
3️⃣ Versionado de la API
Una API cambia con el tiempo. Pero no puedes romper lo que ya funciona.
✅ Versiona tu API:
app/v1/users
app/v2/users
Piensa en una API como un libro:
La primera edición no se cambia.
Si hay mejoras → se publica una nueva edición.
Así mantienes compatibilidad hacia atrás.
Una API cambia con el tiempo. Pero no puedes romper lo que ya funciona.
✅ Versiona tu API:
app/v1/users
app/v2/users
Piensa en una API como un libro:
La primera edición no se cambia.
Si hay mejoras → se publica una nueva edición.
Así mantienes compatibilidad hacia atrás.
7
4⃣ Rate limiting
Protege tu API de abusos y caídas limitando cuántas requests puede hacer un cliente en un tiempo.
Ejemplo de headers:
X-RateLimit-Limit → total permitido
X-RateLimit-Remaining → lo que queda
X-RateLimit-Reset → cuándo se reinicia
Si se pasa del límite → 429 Too Many Requests.
Esto asegura disponibilidad y equidad.
Protege tu API de abusos y caídas limitando cuántas requests puede hacer un cliente en un tiempo.
Ejemplo de headers:
X-RateLimit-Limit → total permitido
X-RateLimit-Remaining → lo que queda
X-RateLimit-Reset → cuándo se reinicia
Si se pasa del límite → 429 Too Many Requests.
Esto asegura disponibilidad y equidad.
8
5⃣ Paginación
No devuelvas 10.000 resultados en una sola request 🚫
👉 Usa paginación:
Offset → ?page=3&limit=20 (simple, pero lento con grandes datasets).
Cursor → ?cursor=abc&limit=20 (eficiente y consistente).
Piensa en leer un libro 📖
No lo lees entero de golpe → lo lees página por página.
No devuelvas 10.000 resultados en una sola request 🚫
👉 Usa paginación:
Offset → ?page=3&limit=20 (simple, pero lento con grandes datasets).
Cursor → ?cursor=abc&limit=20 (eficiente y consistente).
Piensa en leer un libro 📖
No lo lees entero de golpe → lo lees página por página.
9
6⃣ Idempotency
Procesar la misma request varias veces NO debe causar efectos no deseados.
Ejemplo: un pago online 💳
❌ Sin idempotency → cobro duplicado.
✅ Con idempotency → el segundo intento no repite el cargo.
Procesar la misma request varias veces NO debe causar efectos no deseados.
Ejemplo: un pago online 💳
❌ Sin idempotency → cobro duplicado.
✅ Con idempotency → el segundo intento no repite el cargo.
10
Se implementa con un idempotency key (UUID) en el header.
El server guarda la response asociada a esa key.
Así te aseguras de que solo los nuevos requests se procesen.
El server guarda la response asociada a esa key.
Así te aseguras de que solo los nuevos requests se procesen.
11
7⃣ Filtrado y ordenación
Dale flexibilidad al cliente para pedir solo lo que necesita.
👉 Filtros:
/users?role=admin
👉 Ordenación:
/users?sort=created_at&order=desc
Así reduces consumo de ancho de banda y haces la API más usable.
Dale flexibilidad al cliente para pedir solo lo que necesita.
👉 Filtros:
/users?role=admin
👉 Ordenación:
/users?sort=created_at&order=desc
Así reduces consumo de ancho de banda y haces la API más usable.
12
Con estas prácticas tendrás APIs seguras, eficientes y mantenibles 🚀
En resumen👇
En resumen👇
13
Y si quieres seguir aprendiendo cada semana con consejos prácticos para crecer como programador...
📩 Suscríbete a mi newsletter de CERO a SENIOR
Aquí puedes leer la última entrega 👇
🔗ceroasenior.substack.com/p/el-error-que…
📩 Suscríbete a mi newsletter de CERO a SENIOR
Aquí puedes leer la última entrega 👇
🔗ceroasenior.substack.com/p/el-error-que…
