Ideas clave
Diseña las API como contratos duraderos, no como código que puedes refactorizar a la ligera.
Los cambios llegan directamente a los usuarios. Una API web no es como una biblioteca local: quienes la crean controlan el servicio, mientras que los clientes dependen de su interfaz pública. Cambiar el nombre de un campo o modificar una respuesta puede romper software que el equipo de la API no puede actualizar. Geewax evalúa una buena API según cuatro cualidades: funciona, expresa las intenciones de los usuarios, se mantiene sencilla y se comporta de forma predecible.
Los patrones evitan sorpresas costosas. El diseño de API orientadas a recursos aplica un pequeño conjunto de acciones conocidas a recursos con nombre. En el ejemplo del libro, similar a Twitter, devolver 500 000 mensajes de hasta 140 caracteres cada uno podría generar una respuesta de 70 megabytes. Añadir paginación solo después de que los usuarios dependan de la respuesta antigua, que lo devolvía todo de una vez, puede ocultar silenciosamente la mayoría de los mensajes a los clientes existentes. Los patrones son modelos para evitar este tipo de reparaciones estructurales.
El enfoque en los contratos conecta el diseño de API con la gobernanza institucional: una decisión de un equipo limita durante años a muchos equipos independientes. Las convenciones reiteradas reducen el esfuerzo necesario para aprender una interfaz, del mismo modo que un vocabulario compartido ayuda a las personas a coordinarse. Sin embargo, la coherencia no es un fin en sí mismo. Un estándar que obliga a encajar una tarea inusual en una forma poco natural puede trasladar la complejidad a la configuración o a soluciones improvisadas. Por eso, usar bien los patrones requiere tanto disciplina como una explicación clara de los casos en que un patrón no encaja.
Pon nombres claros a los recursos y relaciónalos solo cuando la relación justifique su costo.
Los nombres enseñan a usar la interfaz. Los nombres deben ser expresivos, concisos y coherentes. Si una misma idea aparece como `topic` y como `messagingTopic`, los usuarios no pueden basarse con seguridad en lo que han aprendido. Los nombres de los campos también deben aclarar las unidades: `sizeBytes` es más seguro que `size`. El fracaso del Mars Climate Orbiter ilustra por qué: los valores de una unidad, expresados por un equipo en libras-fuerza segundo, se interpretaron como newton segundo, y se perdió la nave espacial.
Modela solo las relaciones que resulten útiles. Una relación entre recursos debe facilitar un comportamiento real, no limitarse a dar una apariencia de completitud al modelo. Las jerarquías profundas aumentan la información necesaria para localizar un elemento, mientras que convertir cada concepto pequeño en un recurso multiplica los métodos y los identificadores. Incluir datos en línea puede simplificar su recuperación, pero duplicar datos compartidos genera preguntas difíciles sobre las actualizaciones y la coherencia.
Los nombres forman parte del control de errores de un sistema; no son un mero retoque estético. Una unidad precisa o un nombre de campo coherente puede hacer visible una suposición incorrecta antes de que provoque un fallo en tiempo de ejecución. Los diagramas de recursos también obligan a los equipos a abordar quién es dueño de los datos y qué acciones deben propagarse. La contrapartida es que un modelo más normalizado puede requerir llamadas de red adicionales, mientras que uno que incluye datos en línea puede producir respuestas más grandes y actualizaciones ambiguas. La elección correcta depende de los patrones de acceso reales, no de una preferencia universal por normalizar o desnormalizar.
Elige identificadores estables y define explícitamente la semántica de los datos antes de que los clientes dependan de ellos.
Los identificadores sobreviven a los registros. Un buen identificador de recurso es único, permanente, difícil de predecir, fácil de compartir y sencillo de generar. Reutilizar un identificador después de eliminar un recurso puede hacer que una referencia antigua apunte a un recurso completamente distinto. El libro recomienda identificadores de cadena y describe Base32 de Crockford como un formato legible que evita varios caracteres fáciles de confundir. Un dígito de control puede ayudar a distinguir un identificador mal escrito de uno válido que simplemente no tiene ningún recurso asociado.
Los tipos transmiten significado. Decide qué significan los valores ausentes, nulos, vacíos y cero, y documenta las unidades y los límites. Por lo general, es mejor representar como cadenas los identificadores que parecen numéricos, porque no tiene sentido hacer operaciones aritméticas con ellos. En el caso de valores que exceden la precisión numérica habitual, la serialización como cadena puede preservar el valor para que lo procese una biblioteca adecuada del lado del cliente. Las cadenas deben usar UTF-8 y los identificadores deben aplicar la normalización Unicode de manera coherente.
Un identificador funciona como un puntero duradero que se comparte más allá de las fronteras de una organización. La permanencia protege las referencias, mientras que la imprevisibilidad puede dificultar que se adivinen otros recursos. Sin embargo, los identificadores opacos no son un mecanismo de control de acceso: la autorización debe comprobarse en cada solicitud. De igual modo, los tipos y las unidades explícitos reducen la ambigüedad, pero un exceso de detalles puede volver engorrosa una interfaz. La prueba útil consiste en preguntarse si un cliente puede interpretar y validar un valor sin depender de suposiciones ocultas sobre el lenguaje de programación o el sistema de almacenamiento del servidor.
Mantén sencillos los métodos estándar; reserva los métodos personalizados para acciones con consecuencias.
El comportamiento compartido genera confianza. Los métodos estándar son get, list, create, update, delete y, en ocasiones, replace. Su valor reside en que se comportan de forma predecible en distintos tipos de recursos. Update debe modificar los campos especificados; replace hace que el recurso coincida con la representación proporcionada. Los métodos estándar deben evitar efectos secundarios inesperados. Por ejemplo, crear un correo electrónico debe guardarlo como borrador, no enviarlo sin avisar.
Usa un método personalizado para las transiciones. Enviar un correo electrónico cambia el estado y se comunica con sistemas externos, por lo que una acción independiente `SendEmail` deja clara la consecuencia. Los métodos personalizados suelen usar POST y dos puntos para separar la ruta del recurso de la acción. Son flexibles, pero los usuarios no pueden deducir tanto sobre ellos, así que los equipos deben nombrarlos y documentarlos de forma coherente. El trabajo de larga duración puede devolver un recurso de operación en lugar de mantener una solicitud abierta indefinidamente.
La distinción se parece a la que existe entre un comando de base de datos y un proceso de negocio. Una actualización sencilla tiene consecuencias limitadas; enviar un correo puede implicar dependencias remotas, demoras y fallos parciales. Mantenerlos separados facilita razonar sobre la interfaz y diseñar la gestión de fallos. La precaución es que los métodos personalizados pueden convertirse en un refugio para un modelado deficiente de los recursos. Si casi todas las interacciones habituales necesitan una acción a medida, conviene revisar los límites de los recursos subyacentes.
Elige cómo modelar las relaciones según la propiedad, la escala y los metadatos de la relación.
Las referencias no son garantías. Una referencia cruzada almacena el identificador de otro recurso, normalmente en un campo cuyo nombre termina en `Id`. Mantiene pequeños los registros y evita tener que actualizar todas las referencias cuando cambia el recurso de destino. La contrapartida es que una referencia puede apuntar a un recurso eliminado, así que los clientes deben estar preparados para comprobarlo. Copiar recursos relacionados completos en línea puede evitar una consulta, pero conlleva el riesgo de que los datos queden desactualizados y de que las respuestas crezcan.
Usa jerarquías cuando haya propiedad. Las relaciones entre padre e hijo tienen sentido cuando el acceso o la eliminación deben propagarse del padre al hijo. Evita jerarquías profundas para las meras asociaciones, sobre todo cuando un hijo pueda cambiar de padre. En las relaciones de muchos a muchos, un recurso de asociación puede almacenar metadatos como la función de un miembro o cuándo se incorporó. Si la relación solo expresa una conexión de sí o no, los métodos para añadir y quitar pueden ser más sencillos.
El diseño de las relaciones convierte los supuestos del negocio en consecuencias operativas. Una jerarquía codifica más que una URL: sugiere propiedad, herencia de acceso y eliminación en cascada. En cambio, los registros de asociación hacen que la propia relación sea visible y gestionable. Estas decisiones también afectan a los cambios futuros. Es probable que un elemento que puede trasladarse, pero se ubica en una jerarquía de propiedad permanente, requiera una operación de traslado costosa. El desafío útil para quienes diseñan es preguntarse no solo qué está conectado, sino qué debe seguir siendo cierto cuando uno de los lados cambie o desaparezca.
Usa cursores opacos y lotes atómicos para que el trabajo con colecciones sea predecible.
Pide páginas con cursores, no con desplazamientos. La paginación divide los resultados grandes en solicitudes manejables. El cliente pide como máximo `maxPageSize` resultados, devuelve el `nextPageToken` opaco y se detiene cuando ese token está vacío. Que una página sea corta no demuestra que la lista haya terminado. Mantener opaco el token permite al servidor cambiar su estrategia de almacenamiento sin exponer detalles de implementación. La paginación basada en desplazamientos es frágil si llegan registros nuevos entre solicitudes.
Define explícitamente el comportamiento de las operaciones en lote. Las operaciones por lotes get, create, update y delete actúan sobre varios recursos en una sola solicitud. El libro prefiere los lotes atómicos: o todo se completa correctamente o falla la solicitud, en vez de devolver una combinación difícil de interpretar de éxitos y fallos. Los resultados deben conservar el orden de la solicitud, sobre todo cuando la creación asigna identificadores. Los filtros corresponden a los métodos list, para que los clientes no tengan que descargar todos los registros solo para encontrar un subconjunto.
La paginación y las operaciones por lotes resuelven problemas de costos distintos. Los cursores limitan el tamaño de las respuestas y pueden ocultar cómo se almacenan los datos; los lotes reducen las llamadas de red repetidas y pueden ofrecer garantías similares a las de una transacción. La atomicidad simplifica la lógica del cliente, aunque puede provocar que un lote grande falle por un solo elemento no válido. Los cursores opacos tampoco garantizan una vista inmutable de datos que cambian. Si se necesita una instantánea estable, esa garantía debe diseñarse explícitamente, no deducirse de la presencia de un token.
Separa el trabajo de larga duración, las tareas recurrentes y la transferencia de datos en contratos distintos.
Una operación hace seguimiento del trabajo. Una operación de larga duración es un recurso persistente, similar a una promesa, que se devuelve cuando una solicitud puede tardar. Tiene un identificador, un indicador `done`, un resultado o error final y metadatos de progreso opcionales. Los clientes pueden consultarla periódicamente, esperar o, a veces, cancelarla. Una tarea reutilizable (rerunnable job) separa la configuración de la ejecución: los usuarios crean una tarea una sola vez y luego llaman a `run` sin volver a proporcionar sus ajustes. Esto también permite que usuarios distintos configuren y ejecuten el trabajo.
Transfiere los datos de forma deliberada. Los métodos de importación y exportación pueden conectar una API directamente con un almacenamiento externo, con ajustes separados para el acceso al almacenamiento y la conversión de datos. Sirven para mover datos, no para hacer copias de seguridad y restaurarlos: sin instantáneas, una exportación puede combinar registros de momentos distintos. En el caso de las entradas analíticas anónimas, un método de escritura puede incorporar datos sin crear recursos direccionables individualmente, y es posible que los datos no estén disponibles de inmediato.
Estos patrones aclaran tres preguntas que a menudo se confunden: qué trabajo está pendiente, qué tarea debe repetirse y adónde deben viajar los bytes. Separarlas da a quienes operan el sistema más control sobre los permisos, el progreso y la recuperación ante fallos. También deja al descubierto los límites de cada garantía. Un registro de operación no hace que una tarea pueda repetirse, y una exportación no crea una copia de seguridad coherente. La interfaz debe expresar claramente esos límites, sobre todo cuando una etiqueta conocida como «exportación» podría dar a entender un nivel de conservación mayor que el que ofrece el servicio.
Diseña una salida segura para los errores: previsualiza, recupera y deduplica.
Previsualiza antes de destruir. Una solicitud de solo validación comprueba lo que se puede comprobar sin modificar los datos. Si se trata de una eliminación peligrosa basada en criterios, la opción predeterminada debe ser la vista previa, no la ejecución: exige un indicador explícito `force` y devuelve tanto la cantidad como una muestra de los recursos que coinciden. La eliminación lógica quita un recurso de las vistas habituales, pero permite recuperarlo; una acción independiente `expunge` lo elimina permanentemente. Las revisiones del recurso conservan estados anteriores y permiten restaurar uno de ellos creando una nueva revisión actual.
Haz que los reintentos sean seguros. Un identificador de solicitud generado por el cliente permite que el servidor reconozca la repetición de una solicitud no idempotente y devuelva la respuesta almacenada en caché. El servidor también debe comparar una huella digital de la solicitud, de modo que reutilizar un identificador con contenido distinto genere un conflicto, no una respuesta de duplicado engañosa.
Los diseños de seguridad más sólidos cambian la opción predeterminada para que un pequeño descuido no cause una gran pérdida. La vista previa y la eliminación reversible son especialmente valiosas cuando los usuarios no pueden inspeccionar fácilmente de antemano todos los registros afectados. Estas protecciones no sustituyen la autorización, las políticas de retención ni las copias de seguridad. La eliminación lógica puede entrar en conflicto con la obligación legal de borrar datos, y el historial de revisiones puede conservar errores que contienen información sensible. Por tanto, las funciones de seguridad necesitan límites explícitos, incluida la definición de quién puede recuperar registros y cuándo se exige su eliminación permanente.
Trata los reintentos como parte del protocolo, con retroceso y directrices del servidor.
Reintenta solo cuando tenga sentido. Algunos fallos describen una solicitud que seguirá fallando, como el acceso prohibido. Otros pueden ser transitorios, como la indisponibilidad de un servicio. Cuando sea seguro reintentar, el retroceso exponencial aumenta la espera después de cada fallo, mientras que un tiempo máximo de espera y un número máximo de intentos evitan que los intentos continúen indefinidamente. Una variación aleatoria evita que muchos clientes reintenten al unísono y saturen un servicio que se está recuperando.
Usa las indicaciones del servidor que no dependen del reloj. Cuando la API sabe cuándo es probable que una solicitud tenga éxito, puede enviar una duración `Retry-After`. Una duración evita depender de que los relojes del cliente y del servidor estén sincronizados. Para solicitudes no idempotentes cuyo resultado sea incierto, la deduplicación de solicitudes ayuda a evitar trabajo duplicado. Reintentar indiscriminadamente cada error puede repetir acciones o desperdiciar capacidad, por lo que los clientes necesitan tanto reglas de elegibilidad como reglas de temporización.
El comportamiento de los reintentos es un problema de coordinación entre clientes, servidores y redes. El retroceso reduce la presión durante un fallo, mientras que la variación aleatoria evita que los clientes sincronizados conviertan la recuperación en otra interrupción del servicio. Las indicaciones del servidor son más útiles que los cálculos a ciegas de un cliente, pero aun así los clientes necesitan límites razonables y la posibilidad de cancelar. También hay que entender la política de reintentos junto con la semántica de los métodos: un tiempo de espera agotado no demuestra que una escritura no se haya realizado. La deduplicación ayuda a resolver esa incertidumbre, pero solo mientras el servidor conserve el registro de la solicitud correspondiente.
Define las reglas de compatibilidad antes de decidir cómo evolucionarán las versiones de la API.
La compatibilidad es una promesa. Un cambio es compatible con versiones anteriores cuando el código existente de los clientes sigue funcionando según lo previsto, pero lo que se considera «previsto» depende de los usuarios de la API. Añadir un campo puede no causar problemas a un cliente y, sin embargo, superar la memoria disponible en un dispositivo con recursos limitados. Incluso las correcciones de errores o los cambios en los valores predeterminados pueden alterar comportamientos de los que los clientes hayan llegado a depender.
Elige conscientemente una estrategia de versiones. La estabilidad permanente mantiene disponibles las versiones antiguas y añade los cambios incompatibles en versiones nuevas. La inestabilidad ágil ofrece un período de estabilidad más corto y retira las versiones antiguas según un calendario anunciado. El versionado semántico indica los cambios incompatibles con un incremento de la versión principal, las adiciones compatibles con uno de la versión menor y las correcciones compatibles con uno de parche. Cada enfoque implica un equilibrio entre la carga de mantenimiento y la libertad de elección y estabilidad de los usuarios.
La compatibilidad es un acuerdo social expresado mediante una política técnica. Un mismo cambio puede ser seguro para una empresa emergente que actualiza con frecuencia y desestabilizador para un banco o un dispositivo integrado que espera estabilidad a largo plazo. Una política escrita permite debatir esos supuestos antes de que una crisis obligue a tomar una decisión. Las etiquetas de versión por sí solas no bastan: solo comunican lo que la organización ha decidido que significan sus incrementos. El desafío práctico consiste en equilibrar las garantías duraderas con el costo de mantener el comportamiento antiguo y retrasar cambios útiles.
Firma las solicitudes cuando importen la prueba de origen, la integridad y la irrenunciabilidad.
Deben cumplirse tres condiciones. La autenticación debe determinar quién envió una solicitud, garantizar que su contenido no se alteró y, cuando sea necesario, dificultar que el remitente niegue haberla enviado. Las firmas digitales utilizan un par de claves asimétricas: el cliente conserva la clave privada y registra la clave pública con la API. La clave privada firma; la clave pública verifica.
Firma la solicitud completa. Una firma debe abarcar el método HTTP, el host, la ruta, la fecha y un resumen del cuerpo. De lo contrario, un atacante podría cambiar el destino o la acción sin tocar el cuerpo firmado. Esto ofrece garantías mayores que un secreto compartido cuando un tercero debe verificar quién autorizó una solicitud, pero añade costos de cómputo e implementación. En situaciones menos exigentes, puede bastar con la seguridad del transporte y otros métodos de autenticación.
La distinción importante está entre la autenticación para controlar el acceso y las pruebas para resolver disputas posteriores. Un secreto compartido puede demostrar que una de dos partes conocía el secreto, pero no puede probar por sí solo cuál de ellas creó un mensaje. Las firmas de clave pública abordan esa asimetría, mientras que la huella de la solicitud vincula la prueba con el significado de la solicitud. Por consiguiente, el diseño resulta más valioso cuando la auditabilidad es importante. No es automáticamente la mejor opción para el uso cotidiano: la custodia y revocación de claves, la protección contra la repetición de solicitudes y la calidad de la implementación siguen siendo componentes esenciales de un sistema seguro.
Análisis
La idea central del libro es que el diseño de API tiene menos que ver con elegir endpoints ingeniosos que con distribuir la incertidumbre. Cada decisión sobre una interfaz determina quién debe recordar qué, quién asume el costo de un fallo y qué supuestos pueden hacer con seguridad los clientes que están lejos. Los métodos estándar reducen la incertidumbre interpretativa al ofrecer a los usuarios comportamientos reiterados. Los modelos de recursos exponen conceptos duraderos. Las máscaras de campos, los cursores y los recursos de operación explícitos permiten gestionar la complejidad sin convertir cada interacción en algo a medida.
Esa coherencia es una forma de apalancamiento, pero también una limitación. Reutilizar un patrón reduce la carga cognitiva de los clientes y la carga de decidir de los equipos de API. Sin embargo, el patrón puede ocultar costos si un equipo confunde uniformidad con corrección. Un lote atómico puede ser más fácil de entender, pero más difícil de completar. Una jerarquía puede simplificar la autorización y, a la vez, encarecer los traslados. Una versión inmutable puede proteger a los clientes, pero imponer al proveedor la carga de mantener el comportamiento antiguo. El libro resulta más convincente cuando hace visibles estos costos, en lugar de presentar una convención como si fuera mágica.
Una manera útil de leer su catálogo es entenderlo como una secuencia de decisiones sobre límites. Decide qué es un recurso y qué son simplemente datos. Decide si una operación es un cambio de estado sencillo o un proceso externo. Decide si es seguro repetir una solicitud cuando falla, si una eliminación es reversible y si una respuesta describe una instantánea o un sistema cambiante. Estas distinciones determinan si los clientes pueden operar una API de forma segura sin compartir el contexto de quienes la diseñaron.
El resultado es una ética arquitectónica: no obligues a los consumidores a deducir la semántica a partir de los detalles de implementación. Nombra las unidades, mantén opacos los cursores, distingue la vista previa de la ejecución y declara las promesas de compatibilidad antes de que los clientes dependan de ellas. Los patrones no eliminan el criterio necesario para crear una API. Hacen que ese criterio sea legible, reutilizable y menos propenso a redescubrirse a través de fallos en producción.
Resumen de reseñas
API Design Patterns recibe reseñas dispares, con una calificación general de 3,89 sobre 5. Los lectores valoran su cobertura exhaustiva de temas de diseño de API, sus ideas prácticas y su enfoque estructurado. Se elogia el análisis de patrones complejos y la orientación valiosa que ofrece a ingenieros de backend y diseñadores de API. Sin embargo, algunos critican su prolijidad, repetición y ocasional falta de contexto. A pesar de estos inconvenientes, muchos lectores lo consideran una lectura imprescindible para quienes participan en el desarrollo de API, pues ofrece un buen equilibrio entre teoría y ejemplos prácticos.
También leyeron
Glosario
API orientadas a recursos
Acciones estándar sobre recursosUn estilo de API organizado en torno a entidades con nombre que gestiona el servicio, llamadas recursos, en lugar de una larga lista de acciones no relacionadas. Un conjunto pequeño y coherente de métodos, como get, list, create, update y delete, se aplica a esos recursos. El enfoque busca que una API sea más fácil de aprender y más predecible.
máscara de campos
Campos seleccionados del recursoUna lista de rutas de campos que especifica qué partes de un recurso se deben recuperar o actualizar. Al recuperar datos, puede limitar la respuesta a los campos que necesita el cliente. Al actualizar, restringe los cambios a los campos indicados y evita sobrescribir accidentalmente valores que el cliente desconoce.
operación de larga duración
Registro persistente de trabajo asíncronoUn recurso que representa un trabajo que puede tardar demasiado en completarse durante una sola solicitud. Tiene un identificador, un estado de finalización, un resultado o error eventual y metadatos opcionales, como el progreso. Los clientes pueden consultar su estado, esperar a que se complete y, cuando se admita, cancelar o pausar el trabajo.
tarea reutilizable (rerunnable job)
Configuración almacenada de una tareaUn recurso que almacena la configuración de una tarea independientemente de su ejecución. El cliente crea o actualiza la tarea y luego invoca un método run sin volver a enviar su configuración. Esta separación permite ejecutar la tarea periódicamente y que distintos usuarios tengan permiso para configurarla y ejecutarla.
subrecurso singleton
Recurso hijo individual y aisladoUn único recurso hijo que se utiliza para separar una parte de los datos de un recurso principal cuando tiene necesidades distintas de tamaño, seguridad, volatilidad o acceso. Existe porque existe su recurso principal, y al eliminar este también se elimina el subrecurso. Se puede recuperar y actualizar de forma independiente, pero no se crea ni se elimina por separado.
recurso de asociación
Registro direccionable de una relaciónUn recurso que representa una conexión de muchos a muchos entre otros dos recursos. Hace que la relación sea direccionable de manera independiente y puede almacenar metadatos sobre ella, como la función de una persona integrante o la fecha en que se unió. Esta flexibilidad adicional implica más métodos y más conceptos de API que los clientes deben aprender.
paginación
Recuperación de colecciones por partesUn método para devolver colecciones grandes en partes manejables en lugar de una única respuesta enorme. La solicitud indica un tamaño máximo de página y un token de página opaco; la respuesta incluye un token para continuar. La paginación termina cuando el token de la página siguiente está vacío, no necesariamente cuando una página contiene menos resultados de los solicitados.
deduplicación de solicitudes
Gestión segura de solicitudes repetidasUn mecanismo para reconocer que un cliente ha vuelto a enviar una solicitud tras perderse la respuesta. El cliente proporciona un identificador de solicitud y el servicio puede devolver la respuesta original almacenada en caché, en lugar de repetir la acción. Una huella digital de la solicitud ayuda a detectar el uso accidental del mismo identificador para contenido diferente.
eliminación lógica
Eliminación recuperable de recursosUn comportamiento de eliminación que marca un recurso como eliminado y lo quita de las listas habituales sin borrar de inmediato los datos almacenados. Un método independiente para deshacer la eliminación puede restaurarlo, mientras que un método de eliminación definitiva lo borra de forma permanente. Las políticas de caducidad pueden borrar automáticamente los recursos eliminados más adelante.
revisión del recurso
Instantánea del recurso con fecha y horaUna representación guardada de un recurso en un momento concreto de su historial. Las revisiones se pueden enumerar y recuperar, y un estado anterior se puede restaurar creando una nueva revisión a partir de él. El historial de revisiones facilita el diagnóstico y la recuperación, pero aumenta las necesidades de almacenamiento y puede conservar datos confidenciales.
retroceso exponencial
Demoras crecientes entre reintentosUna estrategia de reintento que aumenta el tiempo de espera después de cada intento fallido, normalmente duplicando la demora hasta alcanzar un máximo. Un límite de reintentos evita los intentos interminables, mientras que una variación aleatoria ayuda a impedir que muchos clientes reintenten en oleadas sincronizadas. El servidor puede proporcionar indicaciones de tiempo más específicas mediante una cabecera Retry-After.
Base32 de Crockford
Codificación legible de identificadoresUn formato de codificación utilizado para representar datos de identificadores mediante un alfabeto restringido, diseñado para reducir la confusión al copiar o pronunciar los valores. Omite caracteres que se pueden confundir fácilmente con otros, admite algunas variaciones de entrada comunes y puede incluir un carácter de suma de verificación para ayudar a detectar errores tipográficos.
Preguntas frecuentes
¿De qué trata API Design Patterns, de J.J. Geewax?
- Guía exhaustiva de diseño de API: El libro presenta una colección estructurada de patrones y principios de diseño para crear API web, con énfasis en las API orientadas a recursos.
- Práctico y accesible: Utiliza definiciones de API al estilo de TypeScript y ejemplos del mundo real, como una API similar a Twitter, para ilustrar conceptos a desarrolladores familiarizados con HTTP y la serialización.
- Organizado para facilitar el aprendizaje: El contenido se divide en seis partes, que abarcan los fundamentos de las API, los patrones de diseño, las relaciones entre recursos, las operaciones colectivas y cuestiones de seguridad y protección.
¿Por qué debería leer API Design Patterns, de J.J. Geewax?
- Mejora la facilidad de uso de las API: El libro ayuda a los diseñadores a crear API operativas, expresivas, sencillas y predecibles, lo que contribuye a ofrecer mejores experiencias de usuario y lograr una mayor adopción.
- Ayuda a evitar errores comunes: Condensa años de buenas prácticas y ayuda a los lectores a evitar errores como los nombres incoherentes, la organización deficiente de recursos y los problemas de versionado.
- Coherencia y escalabilidad: Seguir estos patrones hace que las API sean más fáciles de mantener, evolucionar e integrar, en beneficio tanto de quienes las ofrecen como de quienes las usan.
¿Cuáles son las principales conclusiones de API Design Patterns, de J.J. Geewax?
- Patrones y antipatrones: El libro destaca tanto patrones de diseño eficaces como antipatrones comunes, por ejemplo la paginación basada en desplazamientos y los datos insertados en línea, para orientar mejores decisiones sobre las API.
- Aborda conceptos avanzados: Trata temas complejos como la deduplicación de solicitudes, las revisiones de recursos, la autenticación y el versionado, y prepara a los lectores para los retos del mundo real.
- Equilibrio entre teoría y práctica: El libro combina principios fundamentales con consejos prácticos, ejemplos de código y ejercicios para reforzar el aprendizaje.
¿Qué características definen una API «buena» según API Design Patterns, de J.J. Geewax?
- Operativa y fiable: Las API deben hacer de forma fiable lo que los usuarios esperan y cumplir requisitos no funcionales, como la latencia y la precisión.
- Expresiva y sencilla: Los usuarios deben poder expresar claramente su intención sin recurrir a soluciones improvisadas incómodas, y la API debe ser lo más sencilla posible.
- Predecible y coherente: La coherencia en los nombres, el comportamiento y los patrones reduce las sorpresas y facilita aprender a usar las API de manera eficaz.
¿Cómo define y utiliza los patrones de diseño de API API Design Patterns, de J.J. Geewax?
- Modelos reutilizables: Los patrones de diseño de API son soluciones reutilizables a problemas comunes de diseño de interfaces y se centran en la estructura, no en la implementación.
- Aborda la rigidez de las API: Como es difícil cambiar las API una vez que son públicas, los patrones ayudan a acertar con el diseño desde el principio.
- Fomenta la uniformidad: Los patrones promueven la coherencia entre las API, reducen la fragmentación y facilitan su aprendizaje dentro de las organizaciones.
¿Qué convenciones y consejos para los nombres de API ofrece API Design Patterns, de J.J. Geewax?
- Los nombres son fundamentales: Los nombres de las API son públicos y duraderos; por eso, elegir nombres expresivos, sencillos y predecibles es esencial para evitar confusiones y cambios costosos.
- Evita los «olores de API»: Las preposiciones en los nombres suelen indicar problemas de diseño más profundos, y conviene incluir las unidades en los nombres para mayor claridad (por ejemplo, sizeBytes frente a sizeMegapixels).
- Coherencia en toda la API: Las buenas prácticas para nombrar garantizan uniformidad y facilitan el uso y el mantenimiento de las API.
¿Cómo recomienda API Design Patterns, de J.J. Geewax, estructurar los recursos y sus relaciones?
- Organización cuidadosa de los recursos: Elige los recursos con cuidado y define solo las relaciones necesarias (referencias, jerarquías, relaciones de muchos a muchos y autorreferencias) para evitar complejidad.
- Evita los antipatrones: No crees recursos para todo, evita las jerarquías profundas y no insertes en línea todos los datos, para prevenir la confusión y la ineficiencia.
- Modelado de relaciones: Usa recursos de asociación para las relaciones de muchos a muchos y campos de ID de tipo cadena para las referencias, a fin de garantizar flexibilidad e integridad de los datos.
¿Cuáles son los métodos estándar de API y sus características en API Design Patterns, de J.J. Geewax?
- Métodos estándar definidos: El libro destaca Get, List, Create, Update (PATCH), Delete y Replace (PUT) como los métodos principales.
- La coherencia es fundamental: Cada método debe comportarse de forma predecible y coherente en todos los recursos para facilitar al máximo su aprendizaje.
- Idempotencia y efectos secundarios: La mayoría de los métodos son idempotentes, excepto Delete, que debería fallar si el recurso no existe; los efectos secundarios deben reducirse al mínimo para que el comportamiento sea predecible.
¿Cómo aborda API Design Patterns, de J.J. Geewax, las actualizaciones parciales y la recuperación de datos mediante máscaras de campos?
- Selección detallada de campos: Las máscaras de campos permiten a los clientes especificar qué campos recuperar o actualizar, reducen las transferencias de datos innecesarias y facilitan las actualizaciones detalladas.
- Transporte y sintaxis: Las máscaras de campos se envían como parámetros de consulta repetidos y pueden referirse a campos anidados, pero no a elementos de arreglos mediante su índice.
- Valores predeterminados y limitaciones: De forma predeterminada, se devuelven todos los campos, a menos que se especifique lo contrario, y las actualizaciones infieren la máscara a partir de los datos proporcionados.
¿Cuándo y cómo se deben utilizar métodos personalizados en las API según API Design Patterns, de J.J. Geewax?
- Para acciones no estándar: Los métodos personalizados gestionan operaciones con efectos secundarios (por ejemplo, enviar correos electrónicos o lanzar cohetes) que no encajan en los métodos CRUD estándar.
- Separación de responsabilidades: Mantienen las operaciones complejas separadas de la manipulación simple de datos y preservan el carácter acotado de los métodos estándar.
- Implementación coherente: Los métodos personalizados usan POST y dos puntos en la URL (por ejemplo, /resource:action) y deben aplicarse de manera coherente en toda la API.
¿Cómo aborda API Design Patterns, de J.J. Geewax, temas avanzados como la paginación, el filtrado y el versionado?
- Paginación basada en cursores: El libro recomienda usar tokens de página como cursores, en lugar de desplazamientos numéricos, para evitar resultados duplicados o ausentes.
- Filtrado flexible: Promueve filtros de cadenas no estructuradas (como las cláusulas WHERE de SQL) por su facilidad de uso y flexibilidad futura; evalúa un recurso a la vez.
- Estrategias de versionado: Analiza la estabilidad perpetua, la inestabilidad ágil y el versionado semántico, cada uno con sus ventajas y desventajas en cuanto a estabilidad y satisfacción de los usuarios.
¿Qué patrones de seguridad y fiabilidad recomienda API Design Patterns, de J.J. Geewax (por ejemplo, deduplicación de solicitudes, validación y autenticación)?
- Deduplicación de solicitudes: Usa ID de solicitud generados por el cliente para identificar y deduplicar solicitudes no idempotentes, almacenando las respuestas en caché durante un tiempo limitado.
- Validación con
validateOnly: El indicadorvalidateOnlypermite a los clientes previsualizar los resultados de las solicitudes sin ejecutarlas y ayuda a garantizar la seguridad y la corrección. - Autenticación mediante firmas digitales: Los usuarios registran claves públicas en el servidor de la API y firman las solicitudes con claves privadas, lo que garantiza la integridad, la autenticidad y el no repudio.
Descargar PDF
Descargar EPUB
.epub es ideal para leer libros electrónicos en teléfonos, tabletas y lectores electrónicos.