Iniciar prueba gratuita
Popular Nuevos Géneros Autores
EnglishEnglish
EspañolSpanish
简体中文Chinese
繁體中文Chinese (Traditional)
FrançaisFrench
DeutschGerman
日本語Japanese
PortuguêsPortuguese
ItalianoItalian
한국어Korean
РусскийRussian
NederlandsDutch
العربيةArabic
PolskiPolish
हिन्दीHindi
Tiếng ViệtVietnamese
SvenskaSwedish
ΕλληνικάGreek
TürkçeTurkish
ไทยThai
ČeštinaCzech
RomânăRomanian
MagyarHungarian
УкраїнськаUkrainian
IndonesiaIndonesian
DanskDanish
SuomiFinnish
БългарскиBulgarian
עבריתHebrew
NorskNorwegian
HrvatskiCroatian
CatalàCatalan
SlovenčinaSlovak
LietuviųLithuanian
SlovenščinaSlovenian
СрпскиSerbian
EestiEstonian
LatviešuLatvian
فارسیPersian
മലയാളംMalayalam
தமிழ்Tamil
اردوUrdu
Buscando...
SoBrief
API Design Patterns

API Design Patterns

Crea API en las que los clientes puedan confiar, con patrones para cambios más seguros, reintentos y trabajos de larga duración.
por J.J. Geewax 2020 480 páginas
3.86
146 valoraciones
Escuchar
Inmersivo
V2.3
Amazon Kindle Audible
Prueba el acceso completo por 3 días
¡Desbloquea la escucha y mucho más!
Continuar

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.

Análisis

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.

Análisis

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.

Análisis

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.

Análisis

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.

Análisis

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.

Análisis

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.

Análisis

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.

Análisis

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.

Análisis

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.

Análisis

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.

Análisis

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 en 30 segundos
Las API públicas se convierten en dependencias que los equipos no pueden actualizar a voluntad, por lo que importan los nombres, identificadores y significados de datos estables. Las operaciones conocidas facilitan prever el comportamiento, mientras que las acciones personalizadas aclaran los cambios con consecuencias importantes. Los cursores opacos, los lotes atómicos y los registros persistentes de operaciones permiten gestionar tareas grandes o lentas. Previsualiza las solicitudes destructivas, conserva opciones de recuperación y deduplica los reintentos. Las políticas de compatibilidad deben ser explícitas, y las solicitudes firmadas pueden verificar el origen y la integridad.
Contiene spoilers

Última actualización:

Reportar problema

Resumen de reseñas

3.86 de 5
Promedio de 146 valoraciones de Goodreads y Amazon.

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.

Tu valoración:
4.36
214 valoraciones
¿Quieres leer el libro completo?

Glosario

API orientadas a recursos

Acciones estándar sobre recursos

Un 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 recurso

Una 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íncrono

Un 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 tarea

Un 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 aislado

Un ú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ón

Un 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 partes

Un 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 repetidas

Un 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 recursos

Un 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 hora

Una 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 reintentos

Una 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 identificadores

Un 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 indicador validateOnly permite 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.

Sobre el autor

JJ Geewax es el autor de API Design Patterns. Aunque el contenido proporcionado ofrece información limitada sobre el autor, se puede inferir que Geewax tiene una amplia experiencia en diseño y desarrollo de API. La cobertura exhaustiva de temas complejos relacionados con las API que ofrece el libro sugiere que el autor posee profundos conocimientos en la materia. Se describe el estilo de escritura de Geewax como firme en sus opiniones y estructurado, lo que denota una voz segura y experimentada en el tema. Los lectores han recibido, en general, favorablemente el enfoque del autor para explicar patrones de diseño de API, en particular por sus ideas prácticas y su examen minucioso de diversos aspectos del desarrollo de API.

Descargar PDF

Para guardar este resumen de API Design Patterns para más tarde, descarga el PDF gratis. Puedes imprimirlo o leerlo sin conexión cuando quieras.
Download PDF

Descargar EPUB

Para leer este resumen de API Design Patterns en tu dispositivo o aplicación de lectura, descarga el EPUB gratis. El formato de libro digital .epub es ideal para leer libros electrónicos en teléfonos, tabletas y lectores electrónicos.
Download EPUB
¿Quieres leer el libro completo?
Seguir
Escuchar
Inicio
Swipe
Biblio
App
Prueba el acceso completo por 3 días
Escucha, guarda y mucho más
Comparar funciones Gratis Pro
📖 Leer resúmenes
Lee resúmenes ilimitados. Los usuarios gratuitos obtienen 3 al mes
🎧 Escuchar resúmenes
Escucha resúmenes ilimitados en 40 idiomas
—
❤️ Marcadores ilimitados
Usuarios gratuitos limitados a 4
—
📜 Historial ilimitado
Usuarios gratuitos limitados a 4
—
📥 Descargas ilimitadas
Usuarios gratuitos limitados a 1
—
Cronología sin riesgo
Hoy: Obtén acceso instantáneo
Escucha resúmenes completos de más de 26.000 libros. ¡Son más de 12.000 horas de audio!
Día 2: Recordatorio de prueba
Te enviaremos una notificación de que tu prueba está por terminar.
Día 3: Tu suscripción comienza
Se te cobrará el 24 nov,
cancela en cualquier momento antes.
Consume 2.8× More Books
2.8× libros más Escucha Lectura
Nuestros usuarios nos adoran
600,000+ lectores
Trustpilot Rating
TrustPilot
4.6 Excelente
Este sitio es un antes y un después. He leído resúmenes como nunca antes. Lo recomiendo muchísimo.
— Dave G
Vale cada centavo y cada minuto, y está muy bien hecho. Nunca había visto esta calidad de resúmenes en otros sitios. ¡Muy útil!
— Em
¡Muy recomendado! Servicio fantástico. Perfecto para quienes quieren algo más que una sinopsis, pero no todos los detalles de un audiolibro completo.
— Greg M
Ahorra un 62%
Anual
$119.88 $44.99/año/año
$3.75/mes
Mensual
$9.99/mes
Inicia tu prueba gratuita de 3 días
3 días gratis, luego $44.99/año. Cancela cuando quieras.
Unlock a world of fiction & nonfiction books
Más de 26.000 libros por el precio de 2
Lee cualquier libro en 10 minutos
Descubre libros nuevos como en Tinder
Solicita cualquier libro si no está resumido
Lee más libros que cualquiera que conozcas
La app nº 1 para amantes de los libros
Lifelike & immersive summaries
Garantía de devolución de 30 días
Descarga resúmenes en EPUB o PDF
Cancela en cualquier momento con unos clics

¿Por qué solo un resumen?

Escáner
Busca un código de barras para escanear

⭐
⭐
⭐
Tenemos un regalo especial para ti
Abrir
38% de descuento
DESCUENTO PARA TI
⭐
⭐
⭐
$79.99
$49.99/año
Solo $4.16 al mes
Continuar
Empieza con 2 toques y cancela fácilmente
Configuración
General
Widget
Cargando...