Ideas clave
1. Las APIs orientadas a recursos ofrecen un enfoque estandarizado para diseñar servicios web intuitivos y escalables
Las APIs orientadas a recursos son, en esencia, un tipo especial de APIs estilo RPC donde cada llamada sigue un patrón claro y estandarizado: <MétodoEstándar><Recurso>().
La estandarización simplifica el diseño de APIs. Estas APIs se centran en representar los datos como recursos a los que se aplican un conjunto estándar de métodos (GET, POST, PUT, DELETE). Este enfoque aporta varios beneficios:
- Consistencia: los usuarios pueden aprender y entender rápidamente la estructura de la API
- Escalabilidad: se pueden añadir nuevos recursos sin modificar el diseño general
- Previsibilidad: los métodos estándar se comportan de forma similar en distintos recursos
Al organizar las APIs en torno a recursos y métodos estándar, los desarrolladores crean interfaces más intuitivas y fáciles de usar, aprender y mantener a lo largo del tiempo.
2. Convenciones de nombres efectivas y una buena organización de recursos son clave para crear APIs claras y mantenibles
Los buenos nombres, al igual que las buenas APIs, son simples, expresivos y predecibles.
El nombramiento es fundamental en el diseño de APIs. Las convenciones adecuadas y la disposición de recursos impactan significativamente en la usabilidad y mantenimiento de una API:
- Usa nombres claros, concisos y descriptivos para recursos y métodos
- Sigue patrones de nombres consistentes en toda la API
- Evita nombres ambiguos o demasiado genéricos
Consideraciones sobre la organización de recursos:
- Organiza los recursos jerárquicamente cuando sea apropiado
- Usa relaciones significativas entre recursos
- Evita anidamientos profundos que compliquen las URLs
Nombres y estructuras bien diseñados hacen que las APIs sean más intuitivas, reduciendo la curva de aprendizaje y mejorando la experiencia del desarrollador.
3. Los tipos de datos y la definición de campos forman la base de un diseño robusto de APIs
Mientras que el código suele ser privado y oculto en la mayoría de proyectos, las decisiones de diseño en una API están a la vista de todos los usuarios del servicio.
La elección cuidadosa de tipos de datos es crucial. Seleccionar y definir correctamente los tipos y campos afecta la usabilidad, el rendimiento y la extensibilidad futura de la API:
- Elige tipos de datos adecuados para cada campo (por ejemplo, cadena, número, booleano)
- Considera limitaciones de tamaño y posible crecimiento de los datos
- Usa enumeraciones con moderación, prefiriendo campos de texto con validación cuando sea posible
Aspectos clave:
- Campos nulos vs. opcionales
- Valores por defecto y sus implicaciones
- Manejo de estructuras complejas (objetos anidados, arreglos)
Definiendo tipos claros y consistentes, las APIs se vuelven más predecibles y fáciles de integrar con diversas aplicaciones cliente.
4. Los métodos estándar ofrecen consistencia y previsibilidad en las operaciones de la API
Los métodos estándar deberían (y probablemente lo harán) llevar una API al 90% de su funcionalidad. Para el resto de escenarios, existen métodos personalizados que se explorarán en el siguiente capítulo.
Aprovecha los métodos estándar para operaciones comunes. Los métodos estándar (GET, POST, PUT, DELETE) proporcionan una interfaz coherente para interactuar con los recursos:
- GET: obtener información del recurso
- POST: crear nuevos recursos
- PUT: actualizar recursos existentes
- DELETE: eliminar recursos
Ventajas de los métodos estándar:
- Comportamiento predecible en distintos recursos
- Integración simplificada para clientes
- Cumplimiento de principios RESTful
Al basarse en métodos estándar para operaciones comunes, las APIs resultan más intuitivas y fáciles de usar, reduciendo la curva de aprendizaje para los desarrolladores.
5. Los métodos personalizados y las operaciones de larga duración amplían la funcionalidad de la API más allá de las operaciones CRUD estándar
Los métodos personalizados no son un mecanismo para parametrizar métodos estándar.
Extiende las capacidades de la API con métodos personalizados. Cuando los métodos estándar no son suficientes, los métodos personalizados pueden ofrecer funcionalidades adicionales:
- Úsalos para operaciones complejas que no encajan en el modelo CRUD
- Nombra claramente los métodos personalizados para indicar su propósito
- Evita abusar de ellos, ya que pueden aumentar la complejidad de la API
Operaciones de larga duración:
- Gestionan tareas que consumen mucho tiempo de forma asíncrona
- Proporcionan actualizaciones de estado e información de progreso
- Permiten cancelar y reanudar operaciones
Implementando con cuidado métodos personalizados y operaciones prolongadas, las APIs pueden ofrecer funcionalidades avanzadas manteniendo simplicidad y coherencia.
6. Las relaciones entre recursos y el polimorfismo permiten modelar datos complejos en las APIs
El polimorfismo en APIs permite que los recursos adopten distintos tipos para evitar duplicar funcionalidades compartidas.
Modela relaciones complejas de forma efectiva. Las APIs suelen necesitar representar relaciones de datos complejas:
- Uno a muchos: usa recursos anidados o endpoints separados
- Muchos a muchos: implementa recursos de asociación o métodos personalizados
- Polimorfismo: permite que los recursos adopten múltiples formas
Estrategias para modelar relaciones:
- Referencias cruzadas: vincula recursos mediante identificadores
- Recursos anidados: representa relaciones jerárquicas
- Recursos polimórficos: comparte interfaces comunes entre distintos tipos de recursos
Modelar eficazmente las relaciones entre recursos permite que las APIs representen estructuras de datos complejas manteniendo claridad y facilidad de uso.
7. Las operaciones en lote y la paginación facilitan el manejo eficiente de grandes volúmenes de datos
En resumen, la paginación tiene que ver con poder consumir datos cuando la cantidad de recursos o el tamaño de un recurso es demasiado grande para una sola respuesta de la API.
Optimiza para grandes conjuntos de datos. Las APIs a menudo deben manejar grandes cantidades de información de manera eficiente:
Operaciones en lote:
- Permiten crear, actualizar o eliminar múltiples recursos en una sola solicitud
- Mejoran el rendimiento al reducir el número de llamadas a la API
- Mantienen atomicidad para asegurar ejecución total o nula
Paginación:
- Divide grandes conjuntos de resultados en partes manejables
- Usa paginación basada en cursores para mejor rendimiento y consistencia
- Proporciona indicadores claros para la siguiente página de resultados
Implementando operaciones en lote y paginación, las APIs manejan grandes volúmenes de datos con mayor eficiencia, mejorando el rendimiento y la experiencia del usuario.
8. Las estrategias de seguridad y versionado garantizan la fiabilidad y compatibilidad hacia atrás de la API
Cuando no se proporcionan códigos de error (o se solapan, o están pensados para humanos y no para máquinas), se genera la situación preocupante en la que los usuarios de la API pueden empezar a depender del contenido del mensaje para entender qué falla.
Prioriza la seguridad y la compatibilidad. Implementar medidas robustas de seguridad y estrategias de versionado es fundamental para la longevidad de una API:
Consideraciones de seguridad:
- Usa mecanismos adecuados de autenticación y autorización
- Implementa limitación de tasa para prevenir abusos
- Proporciona mensajes de error claros con códigos específicos
Estrategias de versionado:
- Usa versionado semántico para comunicar cambios
- Mantén compatibilidad hacia atrás cuando sea posible
- Documenta claramente los cambios incompatibles y las rutas de migración
Al enfocarse en seguridad y versionado, las APIs mantienen fiabilidad y confianza mientras evolucionan para satisfacer requisitos cambiantes con el tiempo.
Resumen de reseñas
Patrones de Diseño de API ha recibido opiniones encontradas, con una calificación general de 3.89 sobre 5. Los lectores valoran su cobertura exhaustiva de temas relacionados con el diseño de API, sus perspectivas prácticas y su enfoque estructurado. El libro es elogiado por abordar patrones complejos y ofrecer una guía valiosa para ingenieros de backend y diseñadores de API. Sin embargo, algunos critican su extensión excesiva, repetitividad y, en ocasiones, la falta de contexto. A pesar de estas limitaciones, muchos consideran que es una lectura imprescindible para quienes trabajan en el desarrollo de API, ya que ofrece un buen equilibrio entre teoría y ejemplos prácticos.
También leyeron
Preguntas frecuentes
What is API Design Patterns by J.J. Geewax about?
- Comprehensive API design guide: The book presents a structured collection of design patterns and principles for building web APIs, with a focus on resource-oriented APIs.
- Practical and accessible: It uses TypeScript-style API definitions and real-world examples, such as a Twitter-like API, to illustrate concepts for developers familiar with HTTP and serialization.
- Organized for learning: The content is divided into six parts, covering API basics, design patterns, resource relationships, collective operations, and safety/security concerns.
Why should I read API Design Patterns by J.J. Geewax?
- Improve API usability: The book helps designers create APIs that are operational, expressive, simple, and predictable, leading to better user experiences and higher adoption.
- Avoid common pitfalls: It distills years of best practices, helping readers sidestep mistakes like inconsistent naming, poor resource layout, and problematic versioning.
- Consistency and scalability: Following the patterns ensures APIs are easier to maintain, evolve, and integrate, benefiting both providers and consumers.
What are the key takeaways from API Design Patterns by J.J. Geewax?
- Patterns and anti-patterns: The book highlights both effective design patterns and common anti-patterns, such as offset-based pagination and in-line data, to guide better API decisions.
- Advanced concepts covered: It addresses complex topics like request deduplication, resource revisions, authentication, and versioning, equipping readers for real-world challenges.
- Balance of theory and practice: The book combines foundational principles with practical advice, code examples, and exercises to reinforce learning.
What makes a "good" API according to API Design Patterns by J.J. Geewax?
- Operational and reliable: APIs should reliably do what users expect, meeting non-functional requirements like latency and accuracy.
- Expressive and simple: Users must be able to clearly express their intent without awkward workarounds, and the API should be as simple as possible.
- Predictable and consistent: Consistent naming, behavior, and patterns reduce surprises, making APIs easier to learn and use effectively.
How does API Design Patterns by J.J. Geewax define and use API design patterns?
- Reusable blueprints: API design patterns are reusable solutions to common interface design problems, focusing on structure rather than implementation.
- Addressing API rigidity: Since APIs are hard to change once public, patterns help get the design right from the start.
- Promoting uniformity: Patterns encourage consistency across APIs, reducing fragmentation and making APIs easier to learn within organizations.
What naming conventions and advice does API Design Patterns by J.J. Geewax provide for APIs?
- Names are critical: API names are public and long-lived, so choosing expressive, simple, and predictable names is essential to avoid confusion and costly changes.
- Avoid "API smells": Prepositions in names often signal deeper design issues, and units should be included in names for clarity (e.g., sizeBytes vs. sizeMegapixels).
- Consistency across the API: Good naming practices ensure uniformity and make APIs easier to use and maintain.
How does API Design Patterns by J.J. Geewax recommend structuring resources and their relationships?
- Thoughtful resource layout: Carefully choose resources and define only necessary relationships (references, hierarchies, many-to-many, self-references) to avoid complexity.
- Avoid anti-patterns: Don’t create resources for everything, avoid deep hierarchies, and refrain from in-lining all data to prevent confusion and inefficiency.
- Modeling relationships: Use association resources for many-to-many relationships and string ID fields for references, ensuring flexibility and data integrity.
What are the standard API methods and their characteristics in API Design Patterns by J.J. Geewax?
- Standard methods defined: The book emphasizes Get, List, Create, Update (PATCH), Delete, and Replace (PUT) as the core methods.
- Consistency is key: Each method should behave predictably and consistently across all resources to maximize learnability.
- Idempotency and side effects: Most methods are idempotent except Delete, which should fail if the resource doesn’t exist; side effects should be minimized for predictability.
How does API Design Patterns by J.J. Geewax handle partial updates and retrievals using field masks?
- Granular field selection: Field masks let clients specify which fields to retrieve or update, reducing unnecessary data transfer and supporting fine-grained updates.
- Transport and syntax: Field masks are sent as repeated query parameters and can address nested fields, but not array items by index.
- Defaults and limitations: By default, all fields are returned unless specified, and updates infer the mask from provided data.
When and how should custom methods be used in APIs according to API Design Patterns by J.J. Geewax?
- For nonstandard actions: Custom methods handle operations with side effects (e.g., sending emails, launching rockets) that don’t fit standard CRUD methods.
- Separation of concerns: They keep complex operations distinct from simple data manipulation, maintaining the purity of standard methods.
- Consistent implementation: Custom methods use POST and a colon in the URL (e.g., /resource:action) and should be applied consistently across the API.
How does API Design Patterns by J.J. Geewax address advanced topics like pagination, filtering, and versioning?
- Cursor-based pagination: The book recommends using page tokens as cursors instead of numeric offsets to avoid duplicate or missing results.
- Flexible filtering: Advocates for unstructured string filters (like SQL WHERE clauses) for usability and future flexibility, evaluating one resource at a time.
- Versioning strategies: Discusses perpetual stability, agile instability, and semantic versioning, each with trade-offs in stability and user satisfaction.
What security and reliability patterns does API Design Patterns by J.J. Geewax recommend (e.g., request deduplication, validation, authentication)?
- Request deduplication: Use client-generated request IDs to identify and deduplicate non-idempotent requests, caching responses for a limited time.
- Validation with
validateOnly: ThevalidateOnlyflag allows clients to preview request outcomes without executing them, ensuring safety and correctness. - Authentication via digital signatures: Users register public keys with the API server and sign requests with private keys, ensuring integrity, authenticity, and nonrepudiation.
