Domina los principios de diseño de APIs REST y GraphQL para crear interfaces que sean intuitivas, consistentes y un placer de integrar.
Cuándo usarlo: Diseñar APIs REST públicas con buenas prácticas de versionado, errores, autenticación y experiencia de desarrollador.
Herramienta recomendada: Claude
Eres un arquitecto de software especializado en diseño de APIs con experiencia en APIs públicas de alto tráfico. Quiero que me guíes para diseñar una API que otros desarrolladores adopten con entusiasmo, no por obligación. **Mi situación:** Estoy diseñando la API pública de nuestro producto SaaS. Tendrá endpoints para gestionar recursos, autenticación de usuarios, webhooks y un modelo de permisos granular. Quiero que sea la API que yo mismo querría consumir. **Ayúdame con estos aspectos:** 1. **Principios de diseño REST que realmente importan**: Más allá de los verbos HTTP correctos, ¿cuáles son las decisiones de diseño que marcan la diferencia entre una API mediocre y una excelente? Habla de naming de recursos, versionado, idempotencia y diseño orientado a recursos vs orientado a acciones. 2. **Diseño de respuestas consistentes**: ¿Cómo estructuro los envelopes de respuesta para que sean predecibles? Dame una especificación concreta para respuestas de éxito, errores de validación, errores de negocio y errores del servidor. Incluye los campos que siempre deben estar presentes. 3. **Manejo de errores que no frustran**: Los errores mal diseñados son la fuente número uno de frustración para los integradores. Dame una taxonomía de errores con códigos HTTP correctos, error codes semánticos propios, mensajes accionables y enlaces a documentación. 4. **Paginación, filtrado y ordenación**: ¿Cursor-based o offset? ¿Cómo diseño filtros flexibles sin complejidad innecesaria? Dame las convenciones que debo adoptar y los casos edge que debo anticipar. 5. **Autenticación y autorización**: Compara API Keys, OAuth 2.0 con diferentes grant types, y JWT para mi caso de uso. ¿Cómo diseño scopes de permisos granulares sin volverlos imposibles de gestionar? 6. **Webhooks que funcionan en producción**: ¿Cómo diseño el sistema de webhooks para que sea fiable, verificable y fácil de debugear para el integrador? Cubre: payload signing, reintentos, orden de eventos y delivery guarantees. 7. **Versionado sin romper integraciones**: ¿URL versioning vs header versioning? ¿Cómo gestiono la deprecación de endpoints de forma que los integradores confíen en mí como proveedor? 8. **OpenAPI/Swagger como contrato**: ¿Cómo uso la especificación OpenAPI para que sirva de documentación viva, generación de SDKs y validación en CI/CD? Dame la estructura mínima que debo cubrir. 9. **Rate limiting con experiencia de usuario**: ¿Cómo implemento rate limiting que sea fair, predecible y que comunique claramente el estado al desarrollador? Diseña los headers de respuesta y la estrategia de backoff que recomendarías. 10. **Checklist de API review**: Dame una lista de verificación de 20 puntos que pueda usar antes de publicar cualquier endpoint nuevo. Quiero respuestas concretas con ejemplos de JSON, no solo teoría. Empieza por los principios de diseño REST y los errores más comunes que cometen los equipos que diseñan su primera API pública.