Gestión Continua de APIs, 2ª Edición

Capítulo 4. Los pilares de un producto API

Este trabajo se ha traducido utilizando IA. Agradecemos tus opiniones y comentarios: [e-mail]

Cuando se hace bien, parece fácil. La gente no tiene ni idea de lo complicado y difícil que es en realidad. Cuando piensas en una película, la mayoría de la gente se imagina un producto acabado y pulido de dos horas. Pero para llegar a ese producto de dos horas, puede llevar a cientos o miles de personas muchos meses de trabajo a tiempo completo.

George Kennedy

En el capítulo anterior, establecimos la perspectiva de tratar la API como un producto. Ahora echemos un vistazo al trabajo que tendrás que hacer para construir y mantener tu producto. La verdad es que cuesta mucho trabajo desarrollar una buena API. En el Capítulo 1, aprendiste que las API tienen tres partes diferentes: interfaces, implementaciones e instancias. Para crear tu API, tendrás que dedicar tiempo y esfuerzo a gestionar esos tres aspectos. Además, tendrás que mantenerlo todo actualizado a medida que tu producto madure y cambie continuamente. Para ayudarte a comprender y gestionar toda esa complejidad, hemos dividido este cuerpo de trabajo en un conjunto de 10 pilares.

Los llamamos pilares por la forma en que sustentan tu producto API. Si no inviertes en ningún pilar, tu producto está condenado a caer y fracasar. Pero eso no significa que todos los pilares necesiten la máxima inversión para que tu API tenga éxito. En este capítulo, hemos identificado 10 pilares. Lo bueno de tener 10 es que no todos tienen que tener el mismo peso. Algunos pilares pueden ser más fuertes que otros, e incluso puedes decidir que algunos pilares no necesitan mucha inversión en absoluto. Lo importante es que la fuerza combinada de estos pilares eleve tu API, aunque evolucione y cambie con el tiempo.

Presentación de los Pilares

Cada de los pilares de la API forma un límite para un dominio de trabajo. O, dicho de otro modo, cada pilar delimita un conjunto de decisiones relacionadas con la API. En realidad, tu esfuerzo de trabajo no puede clasificarse con esta precisión, y algunos de los pilares se solaparán entre sí. Pero no pasa nada. Nuestra intención no es definir una verdad irrefutable sobre el trabajo de las API, sino desarrollar un modelo útil para examinar y hablar del trabajo que conlleva la producción de productos API. Nos basaremos en este concepto fundamental de pilares a lo largo del libro, a medida que desarrollemos modelos más avanzados para la organización del equipo, la madurez del producto y los aspectos del paisaje en futuros capítulos.

Los 10 pilares que hemos definido para el trabajo de la API son los siguientes:

• Estrategia

• Diseño

• Documentación

• Desarrollo

• Prueba

• Implementación

• Seguridad

• Monitoreo

• Descubrimiento

• Gestión del cambio

En este capítulo, presentaremos cada uno de estos pilares y examinaremos qué son y por qué son importantes para el éxito de un producto API. También describiremos el espacio de decisión de cada pilar junto con algunas orientaciones generales sobre cómo reforzarlo. No te daremos ninguna orientación específica sobre cómo poner en práctica ninguno de los pilares de este capítulo; al fin y al cabo, un análisis completo de cada una de estas áreas de trabajo podría llenar un libro por sí solo, y aún nos quedan muchos más conceptos de gestión de API por abordar. Sin embargo, señalaremos algunas de las decisiones más importantes en cada área desde el punto de vista de la gobernanza. Empecemos echando un vistazo al primer pilar de un producto API: la estrategia.

Estrategia

Los grandes productos de empiezan con una gran estrategia, y los productos API no son diferentes. El pilar de la estrategia de la API incluye dos áreas de decisión clave: por qué quieres crear tu API (el objetivo) y cómo te ayudará una API a conseguir ese objetivo (la táctica). Es importante comprender que tu objetivo estratégico para la API no puede existir en el vacío. Sea cual sea el objetivo que se te ocurra para tu producto API, tiene que aportar valor a la organización que lo posee. Por supuesto, eso significa que, en primer lugar, tendrás que tener alguna idea de la estrategia o el modelo empresarial de tu organización. Si no conoces los objetivos de tu organización, averígualos antes de empezar a crear nuevas API.

Impulsa tu negocio con las API

El impacto que tenga tu producto API en tu estrategia organizativa depende mucho del contexto de tu empresa. Si la principal fuente de ingresos de tu empresa es vender acceso a API a desarrolladores externos (por ejemplo, las API de comunicación de Twilio o la API de pagos de Stripe), entonces la estrategia de tu producto API estará muy entrelazada con la estrategia de tu empresa. Si la API funciona bien, la empresa se beneficia; si la API sufre, la empresa fracasa. El producto API se convierte en el principal canal de valor de tu organización, y su arquitectura y modelo de negocio estarán implícitamente alineados con los objetivos de la empresa.

Sin embargo, la mayoría de las organizaciones tienen negocios "tradicionales" preexistentes a los que darán soporte las API. En estos casos, una API no se convertirá en la nueva fuente principal de ingresos a menos que la empresa realice un cambio importante en su estrategia. Por ejemplo, un banco que lleva cientos de años operando puede abrir una API a desarrolladores externos en apoyo de una iniciativa de "banca abierta". Centrarse únicamente en el modelo de negocio de la API podría llevar a adoptar un modelo de ingresos para la API: cobrar a los desarrolladores por el acceso a las funciones bancarias basadas en la API. Pero pensando en el panorama general para el banco, esta estrategia de la API sería perjudicial porque crea una barrera al uso. En su lugar, la API bancaria puede ofrecerse gratuitamente (con pérdidas) con la esperanza de aumentar el alcance digital del banco, lo que conllevaría un aumento de las ventas de los productos bancarios básicos.

La estrategia de API no es sólo para las API que se ofrecen al mundo exterior; también es un pilar importante para tus API internas. Eso significa que también tendrás que definir una estrategia de producto para ellas. La única diferencia real entre la estrategia de las API internas y la de las externas estriba en los usuarios a los que sirven. Para ambos tipos de API, el trabajo de comprender por qué necesita existir la API y cómo puede satisfacer esa necesidad sigue siendo el mismo. Sea cual sea el contexto de tu API, merece la pena desarrollar un objetivo estratégico para la API que aporte valor a tu organización.

Una vez que tengas un objetivo estratégico para tu producto API, tendrás que desarrollar un conjunto de tácticas que te ayuden a conseguirlo.

Definir las tácticas

Para alcanzar un objetivo estratégico de la API tendrás que crear un plan para tu producto que te lleve hasta allí. Tendrás que desarrollar un conjunto de tácticas para tu trabajo que te ofrezca las mayores posibilidades de éxito. Esencialmente, tu estrategia guía todo el trabajo basado en decisiones que realizarás en los otros nueve pilares. El reto está en comprender el vínculo entre cada uno de esos ámbitos de trabajo basados en decisiones y tu objetivo.

Veamos algunos ejemplos:

Objetivo: aumentar las capacidades alineadas con el negocio en tu plataforma

Si el objetivo es crear un conjunto mayor de API alineadas con la empresa, tu táctica debe incluir algunos cambios en la forma de diseñar y crear tu API en primer lugar. Por ejemplo, probablemente querrás implicar a las partes interesadas de la empresa en las primeras fases del diseño de tu API, para asegurarte de que se exponen las capacidades adecuadas a través de tu interfaz. También es probable que sigas su ejemplo a la hora de comprender quiénes son los usuarios principales y cuáles deben ser los límites de la API.

Objetivo: monetizar los activos internos

Un enfoque de monetización requiere un conjunto de tácticas que te ayuden a llevar tu producto a una comunidad de usuarios que lo encuentre valioso. También suele significar que estarás operando en un mercado competitivo, por lo que la experiencia del desarrollador (DX) al utilizar tu API se vuelve muy importante. Tácticamente, eso significa una mayor inversión en los pilares de trabajo de diseño, documentación y descubrimiento. También significa que tendrás que hacer algunos estudios de mercado para identificar al público adecuado para tu API y asegurarte de que tienes el tipo de producto adecuado para ellos.

Objetivo: cosechar ideas de negocio

Si el objetivo es encontrar ideas innovadoras fuera de tu empresa, tendrás que desarrollar un conjunto de tácticas que fomenten el uso de tu API de forma innovadora. Eso significará comercializar la API de cara al exterior y diseñarla para que resulte atractiva a una comunidad de usuarios que aporte el mayor valor innovador potencial. También tiene sentido invertir mucho en el pilar del descubrimiento para asegurarte de que puedes impulsar el uso al máximo, a fin de cosechar el mayor número posible de ideas. Del mismo modo, necesitarás una táctica clara para identificar las mejores ideas y seguir desarrollándolas.

Como podemos ver en estos tres ejemplos, tendrás que hacer lo siguiente para desarrollar tácticas sólidas para tu API:

• Identifica qué pilares son esenciales para el éxito.

• Identifica qué comunidades de usuarios impulsarán el éxito.

• Reúne datos contextuales para impulsar tu labor de toma de decisiones.

Adaptar tu estrategia

Aunque es importante desarrollar buenas tácticas cuando empiezas a crear tu API, también es esencial que tu estrategia siga siendo fluida y esté preparada para cambiar. No sirve de nada fijar tu objetivo estratégico y tu plan táctico una vez y luego marcharte. En lugar de eso, tendrás que ajustar tu estrategia en función de los resultados que obtengas con tu producto. Si no estás haciendo ningún progreso, tendrás que hacer algunos cambios en tus tácticas, tal vez ajustar tu objetivo o incluso desechar la API y empezar de nuevo.

Trazar tu progreso estratégico significa que necesitarás tener una forma de medir los resultados de tu API. De hecho, es esencial que tengas un conjunto de medidas para tus objetivos estratégicos; de lo contrario, nunca sabrás lo bien que lo estás haciendo. Hablaremos más sobre objetivos y mediciones para las API en el capítulo 7, cuando presentemos los OKR y los KPI para las API. La medición también depende de tener una forma de recopilar datos sobre la API, así que también tendrás que invertir en el pilar del monitoreo.

También debes estar preparado para cambiar tu estrategia si cambia el contexto de tu API: por ejemplo, si tu organización cambia su objetivo estratégico, aparece un nuevo competidor en tu mercado o el gobierno introduce un nuevo tipo de normativa. En cada uno de estos casos, ser rápido en la adaptación puede aumentar enormemente el valor que aporta tu API. Pero el cambio estratégico está limitado por la capacidad de cambio de tu API, por lo que el pilar de la gestión del cambio (que se trata más adelante en este capítulo) es una inversión esencial.

Decisiones clave para la gobernanza de la estrategia

¿Cuál es el objetivo y el plan táctico de la API?

Definir un objetivo y un plan para alcanzarlo es una parte esencial del trabajo de estrategia. Es importante considerar cuidadosamente cómo debe distribuirse este trabajo de decisión. Puedes permitir que los equipos individuales definan sus propios objetivos y tácticas para aprovechar la optimización local, o puedes centralizar la planificación de objetivos para mejorar la optimización del sistema. Si optas por descentralizar el trabajo de estrategia de la API, tendrás que crear incentivos y controles para evitar que una sola API cause un daño irreparable. Por ejemplo, centralizar el paso de autorización de una decisión de fijación de objetivos puede ralentizar el proceso, pero puede evitar problemas inesperados.

¿Cómo se mide el impacto estratégico?

El objetivo de la API es una definición local, pero también tendrás que gobernar lo bien que ese objetivo se alinea con los intereses de la organización. Esa medición puede estar descentralizada y dejarse en manos de tus equipos de API, o puede estar centralizada y estandarizada. Por ejemplo, puedes introducir un proceso coherente con métricas estandarizadas que los equipos deban seguir para los informes de la API. Esto te proporciona la ventaja de disponer de datos coherentes para el análisis a nivel de sistema.

¿Cuándo cambia la estrategia?

A veces es necesario cambiar los objetivos, pero ¿quién puede tomar esa decisión? El problema de cambiar el objetivo de una API es que suele tener un gran impacto, tanto para la propia API como para las personas que dependen de ella. Aunque des libertad a tus equipos para fijar el objetivo de una nueva API, tendrás que introducir más controles para los cambios de objetivo, sobre todo cuando la API haya entrado en una fase de uso intenso.

Diseño

Diseño El trabajo tiene lugar cuando tomas decisiones sobre el aspecto, el tacto y el uso de algo que estás creando. Todo lo que creas o modificas implica decisiones de diseño. De hecho, todo el trabajo de toma de decisiones que describimos en las distintas secciones de este capítulo también puede considerarse trabajo de diseño. Pero el pilar del diseño de API que describimos aquí es especial. Se limita a un tipo concreto de trabajo de diseño: las decisiones que tomas cuando diseñas la interfaz de la API.

Hemos llamado al diseño de la interfaz su propio pilar porque tiene un gran impacto en tu API. Aunque es sólo una parte de lo que constituye una API, la interfaz es todo lo que tus usuarios ven cuando quieren utilizar tu producto. Para ellos, la interfaz es la API. Por eso, cualquier diseño de interfaz que se te ocurra tiene un gran impacto en las decisiones que tomarás en los otros pilares. Por ejemplo, decidir que tu API debe tener una interfaz basada en eventos cambia radicalmente el trabajo de implementación, despliegue, monitoreo y documentación que tendrás que hacer.

Tendrás que tomar muchas decisiones cuando diseñes tu interfaz. He aquí algunas de las cosas importantes que deberás tener en cuenta:

Vocabularios

¿Cuáles son las palabras y los términos que tus usuarios tendrán que entender? ¿Qué caracteres especiales necesitarán conocer?

Estilos

¿Qué protocolos, patrones de mensajes y estilos de interfaz adoptará la interfaz? Por ejemplo, ¿utilizará tu API el patrón CRUD? ¿O utilizará un estilo de eventos? ¿O algo parecido al estilo de consulta GraphQL?

Interacciones

¿Cómo permitirá tu API que los usuarios satisfagan sus necesidades? Por ejemplo, ¿qué llamadas tendrán que hacer para alcanzar sus objetivos? ¿Cómo se les comunicará el estado de las llamadas? ¿Qué tipo de controles, filtros y sugerencias de uso les proporcionarás en la interfaz?

Seguridad

¿Qué características de diseño ayudarán a tus usuarios a evitar cometer errores? ¿Cómo transmitirás los errores y los problemas?

Coherencia

¿Qué nivel de familiaridad proporcionarás a tus usuarios? ¿Será la API coherente con respecto a otras API de tus organizaciones o de tu sector? ¿El diseño de la interfaz será similar al de otras API que hayan utilizado tus usuarios, o les sorprenderá por su innovación? ¿Adoptarás en tu diseño normas industriales ratificadas?

No es una lista exhaustiva, pero como puedes ver, hay mucho terreno de decisión que debes cubrir. Diseñar una buena interfaz es un trabajo difícil. Pero seamos más precisos sobre cuál es el objetivo. ¿Qué es un buen diseño para la interfaz de una API, y cómo tomar mejores decisiones de diseño?

¿Qué es un buen diseño?

Si has hecho el trabajo de establecer una estrategia para tu API, entonces ya has definido un objetivo estratégico para tu API. Tenemos que averiguar cómo el diseño de la interfaz puede ayudarte a acercarte a ese objetivo. Como vimos en "Estrategia", se te pueden ocurrir muchos objetivos y tácticas diferentes para una API. Pero, en general, todas se reducen a elegir entre dos objetivos comunes:

• Consigue más usuarios de la API.

• Reduce los costes de desarrollo por el uso de la API.

En la práctica, necesitarás una visión mucho más matizada de la estrategia si quieres ser eficaz. Pero generalizando los objetivos de esta forma, podemos hacer una observación importante: un buen diseño de la interfaz te ayudará a conseguir estos dos objetivos generalizados. Si la experiencia general de uso de la API es buena, más usuarios estarán dispuestos a utilizarla. El diseño de la interfaz desempeña un papel importante en la experiencia del desarrollador de tu API, por lo que un buen diseño de la interfaz debería conducir a una mayor captación de usuarios. Además, una buena interfaz es la que hace más difícil hacer las cosas incorrectas y más fácil hacer las que resuelven los problemas del usuario. Eso se traduce en un menor esfuerzo de desarrollo para el software que escribas cuando utilices una API bien diseñada.

Por tanto, merece la pena invertir en un buen diseño de interfaz. Pero no hay un conjunto concreto de decisiones que haga que una interfaz sea "buena". La calidad de tu interfaz depende totalmente de los objetivos de tus usuarios. Mejorar la usabilidad y la experiencia es imposible si no sabes para quién estás diseñando. Afortunadamente, si ya has establecido por qué estás construyendo esta API, debería ser un ejercicio bastante sencillo averiguar para quién estás diseñando. Dirígete a esa comunidad de usuarios y toma decisiones de diseño que mejoren su experiencia al utilizar tu API.

Experiencia de Desarrollador (DX)

A lo largo de en este capítulo y en este libro nos referiremos a la experiencia de desarrollador de tu API. En realidad, la DX no es más que la experiencia de usuario que proporciona tu API, pero con el reconocimiento de que es para un tipo de usuario muy particular: un desarrollador de software. La DX de una API es la suma de todas las interacciones que el desarrollador tendrá con tu producto API. El diseño de la interfaz es una parte importante, pero tu documentación, marketing y soporte contribuyen a la experiencia que estás creando. En última instancia, la DX es una medida de lo feliz o (infeliz) que es tu base de usuarios.

Utilizar un método de diseño

Para obtener los mejores resultados de tu trabajo de diseño de interfaces, lo mejor es utilizar un método o proceso. Gran parte de la creación de un diseño consiste en hacer conjeturas o suposiciones sobre lo que crees que funcionará. Tienes que empezar por algún sitio, así que puede que empieces copiando la interfaz de una API que te guste o siguiendo las orientaciones de una entrada de blog. Eso está perfectamente bien. Pero si quieres maximizar el valor que proporciona tu interfaz de diseño, necesitarás una forma de poner a prueba esas suposiciones y asegurarte de que las decisiones que has tomado son las mejores.

Por ejemplo, podríamos decidir adoptar el siguiente proceso ligero:

1. Elabora un prototipo de interfaz.

2. Escribir nuestro propio cliente que utilice el prototipo.

3. Actualiza el prototipo en función de lo que hayamos aprendido y pruébalo una vez más.

Un proceso más pesado podría ser así:

1. Celebra una reunión inicial de diseño con todas las partes interesadas (es decir, usuarios, partidarios y ejecutores).

2. Diseña un vocabulario para la interfaz.

3. Realiza encuestas a la comunidad de usuarios.

4. Crea un prototipo.

5. Prueba el prototipo con las comunidades de usuarios objetivo.

6. Valida el prototipo con los ejecutores.

7. Itera lo que sea necesario.

La gran diferencia entre estos dos ejemplos es la cantidad de inversión que tendrías que hacer y la cantidad de información que reunirías. Decidir cuánto invertir en el proceso de diseño es una decisión estratégica. Por ejemplo, probablemente escudriñarás más la interfaz de una API externa que se venda en un mercado competitivo que la de una API interna que utilice tu propio equipo de desarrollo. Pero recuerda que incluso un proceso de diseño ligero puede reportar grandes dividendos.

Formatos de descripción de la API

Tú puedes facilitar tu trabajo de diseño utilizando una descripción de interfaz legible por máquina para describirla. No todos los estilos de API tienen un formato estándar establecido, pero sí algunos de los más comunes. Por ejemplo, si estás diseñando API SOAP, puedes utilizar el formato WSDL; si estás diseñando una API HTTP de estilo CRUD, puedes utilizar la Especificación OpenAPI; o si estás diseñando API gRPC, puedes utilizar Buffers de Protocolo. Cada uno de estos formatos de descripción te facilita generar prototipos con herramientas y persistir y compartir internamente la descripción de la interfaz como un archivo.

Decisiones clave para la gobernanza del diseño

¿Cuáles son los límites del diseño?

Un equipo de API de sin limitaciones de diseño puede crear un modelo de interfaz que maximice la usabilidad y la experiencia de sus usuarios. Pero la usabilidad está centrada en el usuario y se produce a costa de la flexibilidad para los usuarios en general. Esto significa que este tipo de optimización local tiene un impacto en el sistema. Si estás produciendo muchas API y los usuarios van a necesitar utilizar más de una de ellas, tendrás que introducir algunas restricciones en torno a las decisiones de diseño. Eso significa que tendrás que centralizar el trabajo de diseño o centralizar la selección de opciones que tienen los diseñadores. Algunos equipos centralizados publican una "guía de estilo" para documentar este tipo de restricciones de diseño; puede incluir los vocabularios, estilos e interacciones que están oficialmente permitidos.

¿Cómo se comparten los modelos de interfaz?

Decidir cómo debe compartirse el modelo de una interfaz significa decidir cómo debe persistir el trabajo de diseño de la API. Por ejemplo, si centralizas completamente esta decisión, puedes decidir que todos los equipos de API deben proporcionar los diseños en el formato de descripción OpenAPI. Esto tiene el inconveniente de limitar todas las posibles opciones de diseño a las opciones disponibles en la Especificación OpenAPI, pero también facilita compartir el trabajo entre equipos y utilizar herramientas y automatización coherentes en todo el sistema.

Documentación

No Por muy bien que diseñes la interfaz de tu API, tus usuarios no podrán empezar a utilizarla sin un poco de ayuda. Por ejemplo, puede que tengas que enseñar a los usuarios dónde se encuentra la API en la red, cuál es el vocabulario de los mensajes y la interfaz, y en qué orden deben hacer las llamadas. El pilar de la documentación de la API recoge el trabajo de crear esta experiencia de aprendizaje de la API. Llamamos a este pilar "documentación de la API" en lugar de "aprendizaje de la API" porque las experiencias de aprendizaje de la API más populares se ofrecen en forma de documentación legible por humanos.

Merece la pena proporcionar una buena documentación por la misma razón por la que merece la pena diseñar una buena interfaz: una mejor experiencia para el desarrollador se traduce en un mayor valor estratégico. Si no tienes una buena documentación, la API será más difícil de aprender y comprender. Si es demasiado difícil aprender a usarla, menos gente la utilizará. Si se ven obligados a utilizarla, el software que escriban tardará más en desarrollarse y es más probable que tenga errores. Desarrollar una buena documentación resulta ser una parte importante de la creación de una buena experiencia para el desarrollador.

Métodos de documentación

Tú puedes ofrecer la documentación de la API de muchas formas distintas: puedes proporcionar una referencia similar a una enciclopedia sobre los recursos de tu API, puedes ofrecer tutoriales y contenido conceptual, e incluso puedes proporcionar aplicaciones de ejemplo muy documentadas y complejas para que los usuarios las copien y aprendan de ellas. Existe una increíble variedad de estilos, formatos y estrategias de documentación técnica. Para facilitar las cosas, dividiremos la documentación de la API en dos prácticas amplias y fundamentales: el método de enseñar sin contar y el método de contar sin enseñar. Según nuestra experiencia, tendrás que adoptar ambos enfoques si quieres crear la mejor experiencia de aprendizaje para tus usuarios.

El enfoque de la documentación tell don't teach se centra en comunicar hechos sobre tu API que ayuden a los usuarios a utilizarla. Documentar la lista de códigos de error de tu API y proporcionar una lista de los esquemas de cuerpo de mensaje que utiliza son ejemplos de este enfoque basado en hechos. Este tipo de documentación proporciona a tus usuarios una guía de referencia para tu interfaz. Como es muy factual, es bastante fácil de diseñar y desarrollar. De hecho, es posible que puedas utilizar herramientas para producir este estilo de documentación muy rápidamente, sobre todo si el diseño de la interfaz se ha serializado en un formato legible por máquina (consulta "Formatos de descripción de la API"). En general, este tipo de información objetiva sobre los detalles y el comportamiento de la interfaz requiere menos esfuerzo de diseño y toma de decisiones por parte de tu equipo. Las decisiones clave tienen que ver con elegir qué partes de la API deben documentarse, más que con cómo transmitir esa información de la mejor manera.

Por el contrario, el enfoque de enseñar sin contar de la documentación se centra en diseñar una experiencia de aprendizaje. En lugar de limitarse a exponer los hechos para que los lectores los examinen, este enfoque proporciona una experiencia de aprendizaje personalizada a los usuarios. El objetivo es ayudar a los usuarios de tu API a alcanzar sus objetivos de usabilidad, al tiempo que aprenden a utilizar tu API de forma específica y centrada. Por ejemplo, si tienes una API de mapas, puedes escribir un tutorial de seis pasos que enseñe a tus usuarios a recuperar la información GPS de una dirección. De esta forma puedes ayudarles a realizar una tarea bastante típica con un nivel mínimo de esfuerzo.

Pero la documentación no tiene por qué ser pasiva. Es útil leer referencias, guías y tutoriales, pero también puedes implementar herramientas que ayuden a tus usuarios a conocer tu API de una forma más interactiva. Por ejemplo, puedes proporcionar una herramienta exploradora de API basada en web que permita a tus usuarios enviar solicitudes a tu API en tiempo real. Una buena herramienta exploradora de API es más que una herramienta "tonta" de solicitud de red; guía la experiencia de aprendizaje proporcionando una lista de actividades, vocabularios, sugerencias y correcciones al usuario. La gran ventaja de las herramientas interactivas es que acortan el bucle de retroalimentación para los usuarios: el ciclo de aprender algo, intentar aplicar lo aprendido y aprender de los resultados. Sin herramientas, tus usuarios tendrán que dedicar tiempo a escribir código o a buscar y utilizar herramientas externas, lo que puede dar lugar a un bucle mucho más largo.

El Portal del Desarrollador

En el mundo de las API, un portal para desarrolladores es el lugar (normalmente un sitio web) donde se alojan todos los recursos complementarios de una API. No tienes por qué tener un portal para desarrolladores, pero puede ayudar mucho a mejorar la experiencia de los desarrolladores con tu API, ofreciendo a los usuarios una forma cómoda de conocer tu producto e interactuar con él.

Invertir en documentación

Si en sólo proporcionas un tipo de documentación de la API, lo más probable es que estés desatendiendo a tu comunidad de usuarios. Los distintos usuarios tienen necesidades diferentes, y tendrás que atender a cada una de ellas si te importa su experiencia de aprendizaje. Por ejemplo, los nuevos usuarios pueden beneficiarse mucho del enfoque "enseñar sin contar " de la documentación, porque es prescriptivo y fácil de seguir, pero los usuarios experimentados en tu API apreciarán tu documentación "contar sin enseñar", porque pueden navegar rápidamente hasta los datos que necesitan. Del mismo modo, las herramientas interactivas pueden resultar atractivas para los usuarios que disfrutan de una experiencia en vivo, pero no serán geniales para los usuarios que prefieren comprender y planificar, o simplemente tienen preferencia por la lectura.

En la práctica, proporcionar toda esta documentación para tu API puede ser costoso. Al fin y al cabo, alguien tiene que diseñarla y escribirla, y no sólo una vez, sino durante toda la vida de tu API. En de hecho, una de las dificultades del trabajo de documentación de la API consiste en mantenerla sincronizada con los cambios de interfaz e implementación. Si la documentación es incorrecta, los usuarios pueden quedar descontentos muy rápidamente. Así que tendrás que tomar decisiones inteligentes sobre cuánto esfuerzo de documentación es sostenible para tu producto API.

El factor clave a la hora de tomar tu decisión sobre la inversión en documentación debe ser el valor de mejorar la experiencia de aprendizaje de la API para tu organización. Por ejemplo, una buena documentación puede ayudar a diferenciar un producto de API pública de sus competidores. También puede ser de gran ayuda para una API interna utilizada por desarrolladores que no están familiarizados con el sistema, la empresa o el sector del propietario de la API. El nivel de inversión en documentación para una API pública que opere en un mercado competitivo será normalmente mayor que para una interna, y eso está bien. En última instancia, tendrás que decidir cuánta documentación es suficiente para tu API. La buena noticia es que siempre es posible aumentar esa inversión a medida que crece tu API.

Decisiones clave para la gobernanza de la documentación

¿Cómo debe diseñarse la experiencia de aprendizaje?

Las decisiones en torno al diseño de la experiencia de aprendizaje a menudo se rigen por separado del diseño, implementación y despliegue de una API. Si tienes muchas API, tus usuarios agradecerán tener una experiencia de aprendizaje única y coherente para todas ellas. Pero, centralizar esta decisión conlleva los costes habituales: menos innovación y más limitaciones para los equipos de API, así como un posible cuello de botella de redacción técnica centralizada. Tendrás que equilibrar la necesidad de coherencia con la cantidad de variedad e innovación que necesitas apoyar. Una opción es introducir un modelo híbrido en el que la mayoría de las API tengan una documentación centralizada, pero se permita a los equipos crear sus propias experiencias de aprendizaje si están probando algo nuevo.

¿Cuándo debe redactarse la documentación?

Existe una sorprendente variabilidad en cuanto al momento en que un equipo debe empezar a escribir su documentación. Escribir pronto es más caro debido a la probabilidad de que se produzcan cambios en el diseño y la implementación, pero puede sacar a la luz problemas de usabilidad desde el principio, lo que hace que merezca la pena. Tendrás que decidir si se trata de una decisión que puede descentralizarse con seguridad o si necesita una gestión más centralizada. Por ejemplo, ¿necesita cada API, independientemente de su uso previsto, tener documentación escrita antes de que pueda publicarse? ¿O deben los equipos utilizar su mejor criterio para tomar esa decisión?

Desarrollo

El pilar del desarrollo de API incluye todas las decisiones que tomas cuando das "vida" a tu API. Se trata del duro trabajo de desarrollar la implementación de tu API de forma que se mantenga fiel a su diseño de interfaz. El pilar del desarrollo tiene un espacio de decisión abrumadoramente grande. Tendrás que decidir qué productos tecnológicos y marcos de trabajo quieres utilizar para implementar la API, cómo debe ser la arquitectura de la implementación, qué lenguajes de programación y configuración hay que utilizar, y cómo debe comportarse la API en tiempo de ejecución. En otras palabras, tendrás que diseñar y desarrollar el software de tu API.

La verdad es que a los usuarios de tu API no les importa cómo la implementes. Todas tus decisiones de implementación sobre lenguajes de programación, herramientas, bases de datos y diseño de software carecen de sentido para ellos; sólo importa el producto final. Mientras la API haga lo que se supone que debe hacer y de la forma que se supone que debe hacerlo, tus usuarios estarán contentos. El hecho de que lo haga con una base de datos o un marco de trabajo concretos es sólo una trivialidad para tus usuarios.

Pero que a tus usuarios no les importen tus decisiones no significa que tus decisiones de desarrollo no sean importantes. De hecho, las decisiones de desarrollo importan mucho, especialmente para las personas que tienen que construir, mantener y cambiar la API a lo largo de su vida útil. Si eliges tecnologías difíciles de usar, o lenguajes esotéricos que nadie entiende en tu empresa, la API será más difícil de mantener. Del mismo modo, si eliges herramientas demasiado asfixiantes o lenguajes en los que resulta penoso programar, la API será difícil de cambiar.

Cuando piensas en el pilar de desarrollo de la API, es fácil centrarse sólo en las decisiones que tomarás para construir la primera versión del producto. Eso es importante, pero es sólo una pequeña parte del reto. El objetivo más importante es tomar decisiones de desarrollo que mejoren la calidad, escalabilidad, capacidad de cambio y mantenimiento de tu API durante toda su vida útil. Se necesita experiencia y habilidad para desarrollar software con esa perspectiva, así que tendrás que hacer buenas inversiones en personas y herramientas. Al fin y al cabo, cualquiera puede escribir un programa informático después de unas cuantas clases de programación, pero se necesita un verdadero profesional para escribir programas que funcionen a escala, en uso concurrente, y que manejen todos los casos de perímetro que surgen en la vida real sin dejar de ser mantenibles y modificables por otros desarrolladores.

No hay reglas concretas sobre cómo debes diseñar y diseñar el software de tu API, al igual que no hay reglas concretas para diseñar software en general. Pero, por supuesto, hay mucha orientación, filosofía y consejos sobre cómo debes diseñar tu software. En general, puedes aplicar cualquier buena práctica para el desarrollo basado en servidor al espacio de desarrollo de la API. Lo único que es particular de las API es el saludable ecosistema de marcos y herramientas específicos para el desarrollo de instancias. Echemos un vistazo a los tipos de opciones que tienes para aprovechar estas ayudas.

Utilizar marcos y herramientas

En cualquier proceso de desarrollo típico se utiliza una gran variedad de herramientas, pero para el desarrollo de API, nos interesa una categoría específica de herramientas: las que te ayudan a descargarte de las decisiones relacionadas con la API y del esfuerzo de desarrollo que supone crear una nueva versión de la API. Esto incluye marcos que facilitan la tarea de escribir código API, así como herramientas independientes que ofrecen una implementación "sin código" o "de bajo código".

Una herramienta de especialmente popular en el espacio de la gestión de API es la pasarela de API. Una pasarela API es una herramienta basada en servidor que está diseñada para reducir el coste de la implementación de API en una red. Suelen estar diseñadas para ser altamente escalables, fiables y seguras; de hecho, mejorar la seguridad de la implementación de una API suele ser la principal motivación para introducir una pasarela en la arquitectura de un sistema. Son útiles porque pueden reducir en gran medida el coste de desarrollo de una instancia de API.

El coste de desarrollo disminuye cuando utilizas una herramienta como una pasarela, porque está construida para resolver la mayoría de tus problemas. De hecho, en la mayoría de los casos, estas herramientas requieren muy poco esfuerzo de programación. Por ejemplo, una pasarela API HTTP decente debería estar preparada para escuchar solicitudes en un puerto HTTPS, analizar cuerpos de solicitud JSON e interactuar con una base de datos nada más sacarla de la caja, con sólo un poco de configuración necesaria para hacerla funcionar. Por supuesto, todo esto no ocurre por arte de magia; alguien ha tenido que programar esta herramienta para hacer todas estas cosas. Al final, estás trasladando el coste del desarrollo de la API a una agencia externa.

Cuando las herramientas funcionan bien, son un regalo del cielo. Pero el coste de utilizar herramientas como las pasarelas API es que sólo pueden hacer aquello para lo que están diseñadas. Al igual que con cualquier pieza de maquinaria, tu flexibilidad está limitada a las funciones que proporciona la máquina. Por tanto, elegir la herramienta adecuada se convierte en una importante decisión de desarrollo. Si tu estrategia de API y el diseño de la interfaz te llevan en la dirección de hacer un montón de cosas no estándar, puede que tengas que asumir tú mismo un mayor esfuerzo de desarrollo.

La relación entre interfaz e implementación

Apoyo a la estrategia y el diseño de la interfaz de tu API es realmente el objetivo principal de tu trabajo de desarrollo. Por muy buena que sea tu arquitectura y muy fácil de mantener que sea tu código, si la API no hace lo que el diseño de la interfaz dice que debe hacer, has fracasado. Podemos sacar dos conclusiones de esta afirmación:

• Ajustarse a tu diseño de interfaz publicado es una métrica de calidad importante para tu implementación.

• Tendrás que mantener actualizada tu implementación cada vez que cambies la interfaz.

Eso significa que no puedes desarrollar tu API hasta que tengas un diseño de interfaz. También significa que las personas que realizan tu trabajo de desarrollo necesitan una forma fiable de entender cómo es la interfaz y cuándo cambia. Un gran riesgo para tu producto API es que el equipo de diseño decida un diseño de interfaz que sea poco práctico o imposible de implementar correctamente. Si el diseñador de la interfaz y el desarrollador de la implementación son la misma persona o están en el mismo equipo, no es un gran problema, pero si no es así, asegúrate de que el equipo de implementación examine la interfaz como parte de tu método de diseño de la API.

Utilizar descripciones de API cerca del código

Una forma de mejorar tus posibilidades de mantener sincronizadas la implementación y la interfaz es integrar la descripción de la interfaz en tu implementación. Por ejemplo, si tienes un formato de descripción de la API que representa el diseño de la interfaz, puedes guardar ese archivo en tu repositorio de código o incluso desarrollar una prueba automatizada que verifique tu adherencia a la interfaz. Llevando esto más lejos, puedes incluso generar un esqueleto de código basado en el formato de descripción -aunque eso sólo es realmente eficaz para la primera versión.

También puedes adoptar el enfoque opuesto: en lugar de recibir una descripción de la interfaz y utilizarla con tu código, puedes incrustar a mano la descripción de la interfaz directamente en tu código. Por ejemplo, algunos marcos te permiten utilizar anotaciones que describen una interfaz API. La combinación de tu código y las anotaciones de la interfaz puede convertirse en la "fuente de verdad" de tu interfaz, e incluso puedes utilizarla para generar documentación de la API. Cualquiera de estos enfoques puede ser útil para ayudar a garantizar que tu implementación no rompe una promesa que hace el diseño de tu interfaz.

Decisión clave para la gobernanza del desarrollo

¿Qué se puede utilizar para la aplicación?

Esta es la pregunta central de gobierno para la implementación. Es una pregunta amplia e incluye muchas decisiones dentro de ella: ¿qué bases de datos, lenguajes de programación y componentes del sistema puedes elegir? ¿Qué bibliotecas, marcos y herramientas pueden utilizarse para apoyar el trabajo? ¿Con qué proveedores tienes que trabajar? ¿Se te permite utilizar código fuente abierto?

En el momento de escribir esto, ha habido mucho interés en descentralizar este tipo de decisiones para mejorar la optimización local. Hemos sabido de muchas empresas que han descubierto que sus API son más eficientes, más fáciles de construir y más fáciles de mantener cuando se da más libertad de implementación a los equipos. Pero la descentralización conlleva los costes habituales: menos coherencia y menos oportunidades de optimización del sistema. En la práctica, esto significa que puede ser más difícil para la gente moverse entre equipos, y hay menos oportunidades de obtener economías de escala y menos visibilidad sobre la implementación en general.

Según nuestra experiencia, proporcionar más libertad de implantación merece la pena, pero tendrás que considerar cuánta libertad de decisión puede permitirse tu sistema. Una forma de facilitar el apoyo a las decisiones de implantación descentralizadas es centralizar el elemento de selección, lo que significa centralizar las opciones tecnológicas y descentralizar al mismo tiempo la selección y la autoridad del equipo sobre ellas.

Prueba

Si te importa lo más mínimo la calidad de tu API, tendrás que dedicar algún esfuerzo a probarla. En el pilar de las pruebas de la API, tendrás que tomar decisiones tanto sobre lo que necesitas probar como sobre cómo lo probarás. En general, las pruebas de API no son muy diferentes del típico trabajo de garantía de calidad (GC) que harías para un proyecto de software. Deberías poder aplicar buenas prácticas de calidad del software a la implementación, la interfaz y las instancias de tu API, igual que harías con una aplicación de software tradicional. Pero, al igual que ocurre con el pilar del desarrollo, es el ecosistema de herramientas, bibliotecas y ayudantes lo que hace que el ámbito de las API sea ligeramente diferente del espacio general de las pruebas.

¿Qué hay que probar?

El objetivo principal de probar tu API es asegurarte de que puede cumplir el objetivo estratégico que deberías haber definido durante su creación. Pero, como hemos visto a lo largo de este capítulo, ese objetivo estratégico es posible gracias al trabajo basado en decisiones de los 10 pilares. Por tanto, el objetivo secundario de las pruebas de la API es garantizar que todo el trabajo que has realizado en nuestros pilares tiene la calidad suficiente para respaldar la estrategia. Por ejemplo, si la usabilidad y la facilidad de aprendizaje de tu API son muy bajas, eso podría afectar a un objetivo estratégico de captar más usuarios de la API. Eso significa que tienes que definir pruebas específicas para evaluar la calidad de la interfaz. También tienes que comprobar que el trabajo que has hecho es coherente internamente. Por ejemplo, tendrás que comprobar que la implementación que has desarrollado es coherente con la interfaz que has diseñado.

Aquí tienes una lista típica de categorías de pruebas que utilizan los propietarios de API:

Pruebas de usabilidad y UX

Identifica errores de usabilidad en la interfaz, la documentación y el descubrimiento. Por ejemplo: proporciona la documentación de la API a los desarrolladores y realiza pruebas de observación "por encima del hombro" mientras intentan escribir código cliente utilizándola.

Pruebas unitarias

Identifica errores dentro de la implementación a un nivel granular. Por ejemplo: ejecuta una prueba JUnit contra un método Java en el código de la implementación de la API en cada compilación.

Pruebas de integración

Identifica los errores de implementación y de interfaz realizando llamadas a la API contra una instancia. Por ejemplo: ejecuta un script de prueba que realice llamadas a la API contra una instancia en ejecución de la API en un entorno de desarrollo.

Pruebas de rendimiento y carga

Identifica errores no funcionales en las instancias de la API desplegadas y en los entornos de las instancias. Por ejemplo: ejecuta un script de prueba de rendimiento que simule una carga de nivel de producción contra una instancia en ejecución de la API en un entorno de prueba similar al de producción.

Pruebas de seguridad

Identifica las vulnerabilidades de seguridad de en la interfaz, la implementación y la instancia de la API. Por ejemplo: contrata a un "equipo tigre" para encontrar vulnerabilidades en una instancia en ejecución de la API en un entorno de pruebas seguro.

Pruebas de producción

Identifica los errores de usabilidad, funcionalidad y rendimiento de después de que el producto de la API se haya publicado en el entorno de producción. Por ejemplo: realiza una prueba multivariante con la documentación de la API en la que se sirvan a distintos usuarios versiones ligeramente diferentes del contenido, y mejora la usabilidad de la documentación basándote en los resultados.

Desde luego, ésta no es una lista exhaustiva, y hay muchas otras pruebas que podrías hacer. De hecho, incluso las pruebas que hemos descrito aquí podrían desglosarse en muchas más subcategorías. La gran decisión estratégica que tendrás que tomar en el pilar de las pruebas es cuántas pruebas son suficientes. Lo ideal es que tu estrategia de API te ayude a orientar esta decisión. Si la calidad y la coherencia son una gran prioridad, puede que tengas que dedicar mucho tiempo y dinero a probar tu API antes de lanzarla al mercado. Pero si tu API es experimental, puedes adoptar un enfoque tolerante al riesgo y realizar un nivel mínimo de pruebas. Por ejemplo, cabría esperar que la política de pruebas de la API de pagos de un banco establecido y la API de redes sociales de una startup tuvieran un alcance muy diferente.

Herramientas de prueba de API

Las pruebas pueden ser caras, por lo que resulta útil adoptar mejoras en los procesos que faciliten la mejora de la calidad de tu producto. Por ejemplo, algunas organizaciones han tenido éxito con un método "impulsado por pruebas", en el que las pruebas se escriben antes de crear la implementación o la interfaz. El objetivo de este tipo de enfoque es cambiar la cultura de un equipo para que se centre en las pruebas, de modo que todas las decisiones de diseño den lugar a una implementación más favorable a las pruebas. Cuando funciona, el resultado neto es una API de mayor calidad debido a su comprobabilidad implícita.

Además de las mejoras culturales y de procesos, puedes utilizar herramientas y automatización para reducir el coste de las pruebas. Las herramientas más útiles del arsenal de pruebas de API son los simuladores y los dobles de prueba, o mocks. Esto se debe a que la naturaleza interconectada del software de las API dificulta las pruebas aisladas, por lo que necesitarás alguna forma de simular otros componentes. En concreto, probablemente necesitarás herramientas para simular cada uno de estos componentes:

Cliente

Cuando pruebes tu API, necesitarás algo que pueda simular las peticiones que llegarán de tus clientes de la API. Hay muchas herramientas disponibles que pueden hacer esto por ti. Las buenas te darán suficiente configurabilidad y variabilidad para acercarte mucho a los tipos de mensajes y patrones de tráfico que recibirás en producción.

Backend

Lo más probable es que tu API tenga algunas dependencias propias. Podría tratarse de un conjunto de API internas, una base de datos o un recurso externo de terceros. Para realizar pruebas de integración, rendimiento y seguridad, probablemente necesitarás alguna forma de simular esas dependencias.

Medio ambiente

También necesitarás alguna forma de simular tu entorno de producción cuando realices pruebas de preproducción. Hace años eso podía significar mantener y operar un entorno programado sólo para ese fin. Hoy en día, muchas organizaciones utilizan herramientas de virtualización para abaratar la recreación de entornos para las pruebas.

API

A veces incluso necesitarás simular tu propia API. Puede ser el caso cuando quieras probar uno de tus componentes de apoyo -por ejemplo, un explorador de API en un portal de desarrollo que haga llamadas contra la API-, pero una versión simulada de tu API también es un recurso valioso que puedes ofrecer a los usuarios de tu API. Este tipo de API simulada suele denominarse sandbox, presumiblemente porque es un lugar donde los desarrolladores pueden jugar con tu API y tus datos sin consecuencias. Es una inversión que hay que hacer, pero puede mejorar mucho la experiencia de los desarrolladores con tu API.

Haz que tu cajón de arena parezca de producción

Cuando publiques un sandbox para los usuarios de tu API, asegúrate de que tu sandbox reproduce el entorno de producción lo más fielmente posible. Tendrás un conjunto de usuarios mucho más felices si el único cambio que tienen que hacer cuando terminen de escribir código es dirigirlo a tu instancia de producción. No hay nada más frustrante que dedicar mucho tiempo y energía a solucionar problemas de integración de una API, sólo para descubrir que la instancia de producción tiene un aspecto y un comportamiento diferentes.

Decisiones clave para la gobernanza de las pruebas

¿Dónde deben realizarse las pruebas?

A lo largo de años, los procesos de prueba se han ido descentralizando cada vez más. La gran decisión de gobierno es determinar cuánto quieres centralizar o descentralizar para cada uno de los tipos de etapas de prueba de API que hemos descrito. Centralizar un proceso de pruebas te da más control, pero conlleva el coste de un posible cuello de botella. Parte de esto puede aliviarse con la automatización, pero entonces tendrás que decidir quién configura y mantiene el sistema automatizado. La mayoría de las organizaciones emplean sistemas centralizados y descentralizados. Nuestro consejo es descentralizar las primeras fases de las pruebas por rapidez y centralizar las últimas por seguridad.

¿Cuántas pruebas son suficientes?

Aunque decidas que los equipos individuales pueden ejecutar sus propias pruebas, tal vez quieras centralizar la decisión del nivel mínimo de pruebas que deben realizar. Por ejemplo, algunas empresas utilizan herramientas de cobertura de código que proporcionan informes sobre qué parte del código se ha probado. En términos de métricas y calidad, la cobertura no es perfecta, pero es cuantificable, y te permite establecer un umbral mínimo que todos los equipos deben cumplir. Si cuentas con las personas adecuadas, también puedes descentralizar esta decisión y dejar que los equipos de API individuales hagan lo que sea correcto para sus API.

Implementación

La implementación de una API es lo que da vida a la interfaz, pero esa implementación debe desplegarse adecuadamente para que sea útil. El pilar del despliegue de la API incluye todo el trabajo de trasladar la implementación de una API a un entorno en el que tus usuarios objetivo puedan utilizarla. La API desplegada se denomina instancia, y puede que necesites gestionar varias de estas instancias para mantener tu API funcionando correctamente. El reto del trabajo de implementación de la API consiste en asegurarte de que todas tus instancias se comportan de forma coherente, siguen estando disponibles para tus usuarios y son tan fáciles de cambiar como sea posible.

El trabajo de implementación de software es mucho más complicado hoy que en el pasado. Esto se debe principalmente a que nuestras arquitecturas de software se han vuelto cada vez más complejas, con más dependencias interconectadas que nunca. Además, las empresas tienen expectativas bastante altas en cuanto a la disponibilidad y fiabilidad de los sistemas: esperan que las cosas funcionen siempre y en todo momento. Ah, y no olvides que querrán que los cambios se publiquen inmediatamente. Tendrás que tomar buenas decisiones sobre tu sistema de implementación de API para satisfacer todas esas expectativas.

Afrontar la incertidumbre

Mejorar la calidad de la implementación de una API significa asegurarte de que tus instancias de API se comportan como los usuarios esperan que lo hagan. Obviamente, gran parte del trabajo necesario para que esto ocurra se produce fuera del pilar de la implementación. Tendrás que escribir un código de implementación bueno y limpio, y probarlo rigurosamente si quieres tener menos errores en producción. Pero a veces, incluso cuando tomas todas esas precauciones, ocurren cosas malas en producción. Eso se debe a que hay un alto nivel de incertidumbre e imprevisibilidad con el que lidiar en una API publicada.

Por ejemplo, ¿qué ocurre si se produce un repentino aumento de la demanda de tu producto API? ¿Podrán tus instancias API manejar la carga? ¿O qué pasa si un operador despliega inadvertidamente una versión antigua de una instancia de API, o si un servicio de terceros del que depende tu API deja de estar disponible de repente? La incertidumbre puede surgir de muchos sitios diferentes: de tus usuarios, de errores humanos, de tu hardware y de dependencias externas. Aumentar la seguridad de la implementación requiere que adoptes dos enfoques opuestos al mismo tiempo: eliminar la incertidumbre y, al mismo tiempo, aceptarla.

Un método popular de para eliminar la incertidumbre en las Implementaciones de API es aplicar el principio de inmutabilidad. La inmutabilidad es la cualidad de ser incapaz de cambiar; en otras palabras, ser "sólo de lectura". Puedes aplicar la inmutabilidad de muchas maneras. Por ejemplo, si nunca permites que tus operadores cambien las variables de entorno de un servidor o instalen paquetes de software manualmente, podrías decir que tienes una infraestructura inmutable. Del mismo modo, podrías crear paquetes de implementación de API inmutables, es decir, un paquete desplegable que no pueda modificarse, sólo sustituirse. El principio de inmutabilidad mejora la seguridad porque ayuda a eliminar la incertidumbre introducida por la intervención humana.

Sin embargo, nunca podrás eliminar por completo la incertidumbre. No puedes predecir todas las eventualidades y no puedes probar todas las posibilidades. Por tanto, gran parte de tu trabajo de decisión consistirá en averiguar cómo mantener seguro tu sistema incluso cuando ocurra lo inesperado. Parte de este trabajo se realiza en el nivel de implementación de la API (por ejemplo, escribiendo código defensivo), y parte en el nivel del entorno (por ejemplo, diseñando una arquitectura de sistema resistente), pero gran parte del trabajo debe realizarse en el nivel de implementación y operaciones. Por ejemplo, si puedes monitorear continuamente la salud de tus instancias de la API y los recursos del sistema, puedes encontrar problemas y solucionarlos antes de que afecten a tus usuarios.

Diseñar software resistente

Uno de nuestros recursos favoritos para mejorar la seguridad de una API desplegada es el libro de Michael Nygard ¡Suéltalo! (Librería Pragmática). Si aún no lo has leído, asegúrate de hacerlo. Es un tesoro de patrones de implementación y despliegue para mejorar la seguridad y resistencia de tu producto API.

Un tipo de incertidumbre que te verás obligado a aceptar viene en forma de cambios en la API. Aunque sería agradable congelar todos los cambios una vez que hayas conseguido que tu API funcione de forma fiable, el cambio es una inevitabilidad para la que tendrás que prepararte. De hecho, desplegar los cambios lo más rápidamente posible debería ser un objetivo de tu trabajo de implementación.

Automatización de la Implementación

En realidad, sólo hay dos formas de acelerar tus Implementaciones: hacer menos trabajo y hacer el trabajo más rápidamente. A veces puedes conseguirlo introduciendo cambios en tu forma de trabajar, por ejemplo, adoptando una forma diferente de trabajar o introduciendo un nuevo tipo de cultura. Es difícil, pero puede ayudar mucho. Profundizaremos en este tema más adelante, cuando hablemos de las personas y los equipos en el Capítulo 8.

Otra forma de ir más rápido es sustituir las tareas de implementación humanas por la automatización. Por ejemplo, si automatizas el proceso de prueba, construcción e implementación del código de tu API, podrás realizar lanzamientos con sólo pulsar un botón.

Las herramientas de Implementación y automatización pueden ser una ganancia rápida, pero ten en cuenta los costes a largo plazo. Introducir la automatización en tu flujo de trabajo es como introducir maquinaria en una fábrica: mejora la eficacia, pero limita tu flexibilidad. La automatización también conlleva costes de puesta en marcha y mantenimiento. Es poco probable que funcione nada más sacarla de la caja, y es poco probable que se adapte por sí sola a tus necesidades y contexto cambiantes. Así que, cuando mejores tu sistema con la automatización, prepárate para pagar esos costes a lo largo del tiempo, es decir, los costes de mantenimiento de esa maquinaria, así como su eventual sustitución.

APIOps: DevOps para APIs

A mucho de lo que hemos descrito en esta sección encaja bien con la filosofía de la cultura DevOps. De hecho, existe incluso un término emergente para aplicar las prácticas DevOps a las API, denominado específicamente APIOps. Creemos que DevOps encaja bien en el ámbito de las API y que merece la pena aprender de él, independientemente de cómo quieras llamarlo.

Decisiones clave para la gobernanza de la Implementación

¿Quién decide cuándo puede producirse una liberación?

La pregunta de quién puede liberar es fundamental para la gobernanza de la implementación. Si tienes gente con talento en la que puedes confiar, una arquitectura tolerante a fallos y un dominio empresarial que puede excusar algún fallo ocasional, podrías descentralizar completamente la decisión. De lo contrario, tendrás que averiguar qué partes de esta decisión deben centralizarse. La distribución de esta decisión suele ser matizada. Por ejemplo, podrías habilitar la función "empujar para liberar" para los miembros del equipo de confianza, o liberar a un entorno de pruebas donde un equipo centralizado pueda tomar una decisión de "adelante/no adelante". Distribuye de un modo que se ajuste a tus limitaciones y permita la mayor velocidad, con el nivel adecuado de seguridad a escala.

¿Cómo se empaquetan las Implementaciones?

En los últimos años, la cuestión de cómo se empaqueta y entrega el software ha adquirido una enorme importancia. Ha resultado ser el tipo de decisión que puede cambiar gradualmente todo un sistema en otra dirección. Por ejemplo, la creciente popularidad de la implementación en contenedores ha abaratado y facilitado la creación de implementaciones inmutables y aptas para la nube. Tendrás que considerar quién debe tomar esta importante decisión para tu organización. Un responsable de la toma de decisiones descentralizado y optimizado localmente puede no comprender las repercusiones para la seguridad, la compatibilidad y la escala, pero un responsable de la toma de decisiones puramente centralizado puede no tener una solución que se adapte a la variedad de implementaciones y software que se despliega. Como siempre, es útil algún tipo de restricción de elección y distribución de la decisión.

Más allá de la mera cuestión de centralización y descentralización, también tendrás que considerar qué equipo está mejor situado para tomar la decisión de mayor calidad. ¿Deben los equipos de operaciones y middleware definir las opciones de empaquetado? ¿Un equipo de arquitectura? ¿O deben ser los equipos de implementación los que tomen la decisión? La distribución del talento es un factor clave aquí: ¿qué equipos tienen a las personas que pueden hacer las mejores evaluaciones?

Seguridad

Las API facilitan la conexión entre programas informáticos, pero también introducen nuevos problemas. La apertura de las API las convierte en un objetivo potencial y presenta un nuevo tipo de superficie de ataque. Hay más puertas por las que entrar, ¡y el tesoro es mayor! Así que tendrás que dedicar algún tiempo a mejorar la seguridad de tu API. El pilar de la seguridad de la API se centra en las decisiones que tendrás que tomar para lograr los siguientes objetivos de seguridad:

• Proteger tu sistema, los clientes de la API y los usuarios finales de las amenazas

• Mantener tu API en funcionamiento para su uso legítimo por usuarios legítimos

• Proteger la privacidad de los datos y recursos

Estos tres sencillos objetivos ocultan un tema enormemente complejo. De hecho, un gran error que cometen los propietarios de productos API es suponer que asegurar una API significa simplemente tomar unas cuantas decisiones tecnológicas. Ahora bien, no queremos decir que las decisiones tecnológicas sobre seguridad no sean importantes, ¡por supuesto que lo son! Pero si realmente quieres reforzar el pilar de seguridad de tu API, tendrás que ampliar el contexto de la toma de decisiones basadas en la seguridad.

Adoptar un enfoque holístico

Para que mejore realmente la seguridad de tu API, tendrás que hacer que forme parte del proceso de toma de decisiones de todos los pilares que hemos descrito en este capítulo. Una gran parte de ello es el trabajo de implementar funciones de seguridad en tiempo de ejecución. Para empezar, tendrás que extraer identidades, autenticar clientes y usuarios finales, autorizar el uso e implementar límites de velocidad. Puedes escribir mucho de esto tú mismo, o puedes adoptar el enfoque más seguro y rápido de implementar herramientas y bibliotecas que lo hagan por ti.

Pero la seguridad de la API incluye muchas cosas que ocurren fuera de la interacción del software cliente-API. Los cambios culturales pueden mejorar la seguridad inculcando a ingenieros y diseñadores la mentalidad de que la seguridad es lo primero. Se pueden implantar procesos para evitar que los cambios inseguros lleguen a producción o permanezcan en producción. Se puede revisar la documentación para asegurarse de que no filtra información inadvertidamente. Se puede formar al personal de ventas y asistencia para que no facilite inadvertidamente datos privados ni colabore en un ataque de ingeniería social.

Por supuesto, lo que acabamos de describir es mucho más amplio que el ámbito tradicional de la seguridad de las API. Pero lo cierto es que la seguridad de las API no puede existir por sí sola. Forma parte de un sistema interconectado y debe considerarse como un elemento más de un enfoque holístico de la seguridad de tu empresa. No sirve de nada pretender que es una isla en sí misma sin conexión con tu estrategia de seguridad más amplia. Las personas que quieran explotar tu sistema seguro que no lo tratarán así.

Por tanto, tendrás que tomar decisiones sobre cómo integrar tu trabajo de API con la estrategia de seguridad de tu empresa. A veces eso es bastante fácil de hacer, y otras veces es más difícil. Uno de los grandes retos de las API consiste en equilibrar el deseo de apertura y usabilidad con el deseo de bloquear las cosas. Lo lejos que llegues en uno u otro sentido debe ser producto de tu estrategia organizativa y de los objetivos estratégicos de tu API.

Decisiones clave para la gobernanza de la seguridad

¿Qué decisiones hay que autorizar?

Todas las decisiones que toman las personas en tu organización tienen el potencial de introducir una vulnerabilidad de seguridad, pero es imposible escudriñar cada decisión que se toma. Tendrás que determinar qué decisiones tienen el mayor impacto en la seguridad de tu API y asegurarte de que esas decisiones son las mejores. Eso va a depender mucho de tu contexto. ¿Hay zonas "de confianza" en tu arquitectura que necesitan tener "perímetros" seguros? ¿Tienen ya experiencia en buenas prácticas de seguridad los diseñadores e implementadores? ¿Todo el trabajo se realiza internamente o trabajas con terceros? Todos estos factores contextuales pueden cambiar tu enfoque de la autorización de decisiones.

¿Cuánta seguridad necesita una API?

Una gran parte del aparato de seguridad es la normalización de las decisiones de trabajo para proteger el sistema y a sus usuarios. Por ejemplo, puedes tener normas sobre dónde pueden almacenarse los archivos o qué algoritmos de encriptación deben utilizarse. Una mayor estandarización disminuye la libertad de los equipos y las personas para innovar. En el caso del contexto de la seguridad, esto suele justificarse por el impacto de tomar una única decisión equivocada, pero no todas las API necesitan necesariamente el mismo nivel de escrutinio y protección. Por ejemplo, una API utilizada por desarrolladores externos para transacciones financieras necesitará más inversión en seguridad que una API utilizada para registrar datos de rendimiento. Pero, ¿quién toma esa decisión?

Como siempre, el contexto, el talento y la estrategia son las consideraciones clave. Centralizar esta decisión permite a un equipo de seguridad hacer una evaluación general basada en su comprensión del contexto del sistema. Sin embargo, a veces este tipo de normas generalizadas hacen posible que las cosas se escapen entre las grietas, especialmente cuando los equipos de API están haciendo cosas nuevas e innovadoras que el equipo centralizado no podría haber tenido en cuenta. Si la decisión está distribuida, los propios equipos pueden tomar una decisión de evaluación, pero esto requiere un nivel decente de conocimientos de seguridad dentro del propio equipo. Por último, si operas en un ámbito que prioriza la seguridad y la mitigación de riesgos, puedes acabar forzando el máximo nivel de seguridad sobre todo, sin tener en cuenta el contexto local y el impacto sobre la velocidad.

El Proyecto OWASP de Seguridad de la API

El Proyecto OWASP de Seguridad de las API de es un recurso fantástico para comprobar que has actuado con la diligencia debida para asegurar tu API. El Proyecto Abierto de Seguridad de Aplicaciones Web (OWASP) es una fundación sin ánimo de lucro, basada en la comunidad, que proporciona orientación sobre la seguridad de las aplicaciones web. En los últimos años, han estado apoyando a la comunidad con material específico sobre API para ayudar a abordar las amenazas más comunes a las que se enfrentan los propietarios de API. Si quieres tomar mejores decisiones sobre la seguridad de tu API, asegúrate de que tu equipo ha leído y comprendido los consejos de seguridad de la API del OWASP antes de empezar el diseño y el desarrollo.

12 Principios de seguridad de la API

Derivada de la lista de comprobación de seguridad de Yuri Subach aplicada a las API, la siguiente es una lista de comprobación de los 12 principios fundamentales de la seguridad de las API que puedes utilizar para guiar a tu equipo hacia unas API seguras y protegidas:

Confidencialidad de la API

Limitar el acceso de a la información es la primera regla de la seguridad de la API. El recurso accesible a través de la API debe estar disponible sólo para usuarios autorizados, y protegido de destinatarios no deseados durante el tránsito, el procesamiento o en reposo.

Integridad de la API

La información proporcionada por la API debe ser siempre fiable y precisa. El recurso debe estar protegido de alteraciones, modificaciones o supresiones intencionadas y no intencionadas, y los cambios no deseados deben detectarse automáticamente.

Disponibilidad de la API

Disponibilidad es una garantía de acceso fiable a la información por parte de las personas autorizadas. La disponibilidad viene acompañada de sus requisitos, a nivel de infraestructura y aplicación, combinados con procesos de ingeniería adecuados en la organización.

Economía de mecanismo

Diseño de la API y la implementación del sistema deben ser lo más sencillas posible. Las API complejas son difíciles de inspeccionar y mejorar, y son más propensas a errores. Desde el punto de vista de la seguridad y la usabilidad, el minimalismo es algo bueno.

Valores predeterminados de la API a prueba de fallos

El acceso a cualquier punto final/recurso de la API debe denegarse por defecto, y el acceso sólo debe concederse en caso de permiso específico. Una buena seguridad de la API sigue el esquema de protección "cuando debe concederse el acceso" y no sigue el esquema de protección "cuando debe restringirse el acceso".

Mediación completa

El acceso a todos los recursos de una API debe estar siempre validado. Cada punto final debe estar equipado con un mecanismo de autorización. Este principio lleva las consideraciones de seguridad al nivel de todo el sistema.

Diseño de API abierta

Un buen diseño de la seguridad de la API no debe ser un secreto y debe documentarse y basarse en normas de seguridad definidas y protocolos abiertos. La seguridad de la API implica a todas las partes interesadas de la organización y puede incluir también a socios o consumidores.

Mínimo privilegio API

Cada consumidor de API del sistema debe funcionar con los permisos de API mínimos necesarios para realizar su trabajo. Esto limita el daño causado por un accidente o error relacionado con este consumidor específico de la API.

Aceptabilidad psicológica

Una implementación eficaz de la seguridad de la API de debe proteger un sistema, pero sin obstaculizar a los usuarios del mismo para que lo utilicen adecuadamente ni disuadirles de seguir todos los requisitos de seguridad. El nivel de seguridad de la API debe ajustarse al nivel de amenaza. Un mecanismo de seguridad de API pesado para recursos no sensibles puede ser desproporcionado en términos de esfuerzos para los consumidores.

Minimizar la superficie de ataque de la API

Limitar superficie de ataque de una API es la minimización de lo que puede ser explotado por usuarios malintencionados. Para reducir el área de ataque superficial de la API, puedes exponer sólo lo necesario y limitar el daño del área limitando el alcance y la velocidad, estrangulando el número de llamadas a la API antes de la validación adicional del usuario, y actuando con la debida diligencia en los casos de uso.

API defensa en profundidad

Las múltiples capas de control de dificultan la explotación de una API. Puedes limitar el acceso al servidor a varias direcciones IP conocidas (etiqueta blanca), imponer la autenticación de dos factores e implantar muchas otras técnicas que aumenten la profundidad de tu práctica de seguridad de la API.

Política de confianza cero

La política de confianza cero de significa considerar inseguros por defecto a los proveedores de API de terceros y a los consumidores de API de terceros, ya sean externos o internos. Eso significa aplicar todas las medidas de seguridad pertinentes de las API internas y externas como si todas fueran externas y no fiables por defecto.

Falla las API de forma segura

Todas las API de fallan a menudo al procesar las transacciones debido a una entrada incorrecta, una sobrecarga de solicitudes u otras razones. Cualquier fallo dentro de la instancia de la API no debe anular los mecanismos de seguridad y debe denegar el acceso en caso de fallo.

Solucionar correctamente los problemas de seguridad de la API

Una vez identificado un problema de seguridad de la API, céntrate en solucionarlo adecuadamente y evita las "soluciones rápidas" que pueden servir a corto plazo, pero que no solucionan la causa real del problema. Los desarrolladores y los expertos en seguridad de la API deben comprender la causa raíz del problema, crear una prueba para ello y solucionarlo con un impacto mínimo en el sistema. Una vez hecho el arreglo, el sistema debe probarse en todos los entornos compatibles y en todas las plataformas. A menudo, las violaciones de la seguridad de la API se producen por fallos que fueron identificados por el equipo de la API, pero que no se solucionaron correctamente.

Monitoreo

Fomentar la calidad de la observabilidad en tu producto API es importante. No puedes gestionar adecuadamente tu API a menos que dispongas de información precisa y actualizada sobre cómo está funcionando y cómo se está utilizando. El pilar del monitoreo de la API tiene que ver con el trabajo que tienes que hacer para que esa información esté disponible, sea accesible y útil. Con el tiempo y a escala, el monitoreo de las instancias de la API resulta ser tan esencial para la gestión de la API como el diseño de la interfaz o el desarrollo de la implementación: si estás a oscuras, no puedes evitar tropezar y caer.

Hay muchas cosas que se pueden monitorizar en una instancia de la API:

• Problemas (por ejemplo, errores, fallos, advertencias y bloqueos)

• Estado del sistema (por ejemplo, CPU, memoria, E/S, estado del contenedor)

• Salud de la API (por ejemplo, tiempo de actividad de la API, estado de la API y total de mensajes procesados)

• Registros de mensajes (por ejemplo, cuerpos de mensajes de solicitud y respuesta, cabeceras de mensajes y metadatos)

• Datos de uso (por ejemplo, número de solicitudes, uso de puntos finales/recursos y solicitudes por consumidor)

Más información sobre el monitoreo

A excepción del monitoreo de la API y del uso, los tipos de mediciones que hemos descrito no son exclusivos de los componentes de software basados en la API. Si buscas una buena guía para el monitoreo de componentes de software basados en red, te animamos a que leas Site Reliability Engineering (O'Reilly) de Google. Es una gran introducción al diseño de sistemas de software e incluye una lista bastante completa de los tipos de cosas que deberías monitorizar. Otro buen recurso al que echar un vistazo es el Método RED de Weaveworks, que identifica tres categorías de métricas para un microservicio: tasa, errores y duración.

Cada uno de estos grupos de métricas ayudará a tu API de formas distintas. Los datos de salud y problemas te ayudarán a detectar y tratar los fallos, reduciendo idealmente el impacto de cualquier problema que surja. Los datos de procesamiento de mensajes pueden ayudarte a solucionar problemas de la API y del sistema. Las métricas de uso pueden ayudarte a mejorar tu producto API, ayudándote a comprender cómo utilizan realmente tu API tus usuarios. Pero primero, tendrás que ponerte manos a la obra para que esos datos estén disponibles. Por supuesto, también tendrás que asegurarte de que dispones de una forma fiable de recopilar todos esos datos y presentarlos de forma utilizable.

Cuantos más datos puedas producir, más oportunidades tendrás de aprender y mejorar tu producto. Así pues, lo ideal sería que produjeras un flujo interminable de datos para tu API. Sin embargo, los costes de producción, recopilación, almacenamiento y análisis de datos pueden ser muy elevados, y a veces son insoportables; por ejemplo, si el tiempo de ida y vuelta de tu API se duplica porque necesita registrar datos, tendrás que reducir parte de tu registro o encontrar una forma mejor de hacerlo. Una de las decisiones más importantes que tendrás que tomar es qué puedes permitirte monitorizar teniendo en cuenta los costes conocidos.

Otra decisión importante es la coherencia que tendrá el monitoreo de tu API. Si la forma en que tu API proporciona los datos de monitoreo es coherente con otras herramientas, normas del sector o convenciones de la organización, será mucho más fácil de usar. Diseñar el sistema de monitoreo es muy parecido a diseñar una interfaz. Si tu interfaz de monitoreo es completamente única, llevará más tiempo aprender a utilizarla y a recopilar datos. Eso está bien cuando tienes una sola API y eres el único que la monitoriza, pero a escala de decenas o cientos de API, necesitarás reducir ese coste de monitorización. Exploraremos más esta idea en el Capítulo 7.

Decisiones clave para el monitoreo de la gobernanza

¿Qué hay que monitorear?

La decisión de qué monitorizar es importante. Puedes dejarlo en manos de equipos individuales al principio, pero a escala, te beneficiarás si tienes consistencia en el monitoreo de tu API. Unos datos coherentes mejorarán tu capacidad de observar los impactos y el comportamiento del sistema. Eso significa que tendrás que centralizar parte de esta toma de decisiones.

¿Cómo se recogen, analizan y comunican los datos?

Centralizar las decisiones sobre la implementación del monitoreo facilitará el trabajo con los datos de la API, pero puede coartar la libertad de los equipos de API. Tendrás que decidir qué parte de esta decisión debe centralizarse y qué parte debe distribuirse y descentralizarse. Esto es especialmente importante cuando se trata de datos sensibles que deben protegerse.

Descubrimiento

Una API sólo es valiosa si se utiliza, pero para que se utilice, primero hay que encontrarla. El pilar del descubrimiento de API tiene que ver con el trabajo necesario para que tus API sean más fáciles de encontrar para tus usuarios objetivo. Esto significa ayudar a los usuarios a comprender fácilmente qué hace tu API, cómo puede ayudarles, cómo pueden empezar a utilizarla y cómo pueden invocarla. El descubrimiento es una cualidad importante de la experiencia del desarrollador de tu API. Requiere un buen diseño, documentación y opciones de implementación, pero también tendrás que hacer algún trabajo adicional específico de descubrimiento para mejorar realmente la capacidad de localización de tu producto API.

En el mundo de las API, hay dos tipos principales de descubrimiento: en tiempo de diseño y en tiempo de ejecución. El descubrimiento en tiempo de diseño se centra en facilitar a los usuarios de la API el conocimiento de tu producto API. Eso incluye conocer su existencia, su funcionalidad y los casos de uso que puede resolver. Por el contrario, el descubrimiento en tiempo de ejecución tiene lugar después de que tu API haya sido implementada. Ayuda a los clientes de software a encontrar la ubicación de red de tu API basándose en un conjunto de filtros o parámetros. El descubrimiento en tiempo de diseño se dirige a los usuarios humanos y es principalmente un ejercicio de promoción y marketing. La detección en tiempo de ejecución se dirige a clientes máquina y se basa en herramientas y automatización. Echemos un vistazo a cada uno de ellos.

Descubrimiento en tiempo de ejecución

Descubrimiento en tiempo de ejecución es una forma de mejorar la capacidad de cambio de tu entorno API. Si tienes un buen sistema de descubrimiento en tiempo de ejecución, puedes cambiar la ubicación de tus instancias de API con muy poco impacto en los clientes de la API. Esto es especialmente útil si hay muchas instancias de API ejecutándose al mismo tiempo; por ejemplo, las arquitecturas de microservicios a menudo admiten el descubrimiento en tiempo de ejecución para facilitar la búsqueda de servicios. La mayor parte del trabajo que tendrás que hacer para que esto ocurra se encuentra en los pilares de desarrollo e implementación de una API.

El descubrimiento en tiempo de ejecución es un patrón útil que debes conocer y que merece la pena poner en práctica si gestionas un sistema complejo de APIs. No tendremos tiempo de entrar en los detalles de implementación de cómo hacerlo funcionar, pero requiere una inversión en tecnología a nivel de entorno, API y consumidor. En general, cuando hablamos del pilar de descubrimiento en este libro, nos referimos al descubrimiento en tiempo de diseño.

Descubrimiento en tiempo de diseño

Para que ayude a la gente a conocer tu API en el momento del diseño, tendrás que asegurarte de que dispones del tipo adecuado de documentación sobre la API. La documentación sobre lo que hace tu API y qué problemas resuelve debe estar fácilmente disponible para los usuarios que la busquen. Este tipo de "copia" de marketing de producto es una parte esencial del descubrimiento, pero no es lo único que importa. Ayudar a tus usuarios a encontrar esa información en primer lugar resulta ser una parte crítica de este pilar. Tendrás que comprometerte con tu comunidad de usuarios y comercializar con ellos para tener éxito. Cómo lo hagas depende mucho del contexto de tu base de usuarios:

APIs externas

Si tu API está siendo utilizada principalmente por personas que no trabajan en tu grupo u organización, tendrás que invertir en hacerles llegar tu mensaje. Esto significa comercializar tu producto API del mismo modo que comercializarías un programa informático: optimización de motores de búsqueda, patrocinio de eventos, participación de la comunidad y publicidad. Tu objetivo es asegurarte de que todos los usuarios potenciales de tu API entienden cómo puede ayudarles tu producto a satisfacer sus necesidades. Por supuesto, las acciones concretas de marketing que emprendas dependerán mucho de tu contexto, de la naturaleza de la API y de los usuarios a los que te dirijas.

Por ejemplo, si estás desarrollando un producto de API SMS y compites por los desarrolladores-usuarios, entonces te anunciarás en los lugares donde esperas que estén tus usuarios potenciales: conferencias de desarrolladores web, blogs sobre autenticación de dos factores y conferencias de telecomunicaciones. Si te diriges a desarrolladores independientes, podrías confiar en la publicidad digital, pero si tu objetivo son las grandes empresas, podrías invertir en un equipo de vendedores y en su red de relaciones. Si compites en un mercado saturado, probablemente tendrás que esforzarte mucho para diferenciarte, pero si tu producto es único, puede que sólo necesites un poco de magia de optimización de motores de búsqueda para que la gente entre por la puerta. Cuando se trata de marketing de productos, el contexto es el rey.

API internas

Si tu API está siendo utilizada por tus propios desarrolladores, probablemente tengas un público cautivo. Pero eso no significa que puedas ignorar la capacidad de descubrimiento de tu API. Una API interna tiene que ser descubierta para ser utilizada, y con el tiempo, si es demasiado difícil de encontrar, tendrás problemas. Si los desarrolladores internos no la conocen, no podrán utilizarla e incluso podrían perder el tiempo creando otra API que haga lo mismo que la tuya. Un mercado competitivo de API internas suele ser una señal saludable, y la reutilización suele estar sobrevalorada en las empresas. Pero si la gente de tu empresa está duplicando API perfectamente buenas sólo porque no las conoce, es una sangría de recursos.

Las API internas pueden comercializarse de forma muy parecida a las API externas. Sólo que el ecosistema de marketing es diferente. Mientras que con una API externa probablemente te dirigirás al motor de búsqueda de Google, para una API interna puede que sólo necesites entrar en la hoja de cálculo corporativa que enumera las API de la empresa. Patrocinar una conferencia de desarrolladores puede ser eficaz para una API externa, pero una estrategia mejor para una API interna podría ser simplemente visitar a todos los equipos de desarrollo de la empresa y enseñarles tu API.

Un gran reto para la comercialización de API internas suele ser la falta de madurez y normalización en la organización. En realidad, si comercializas tus API en una gran empresa, es muy probable que haya más de una lista de API flotando por ahí. Para hacer un buen trabajo, tendrás que asegurarte de que tu API está en todas las listas y registros importantes. Del mismo modo, conocer y conseguir tiempo con todos los equipos de desarrollo de tu empresa puede ser difícil en la práctica, pero si el uso de tu API te importa, merece la pena hacer la inversión.

Decisiones clave para la gobernanza del descubrimiento

¿Cómo será la experiencia de descubrimiento en?

Tendrás que diseñar una buena experiencia de descubrimiento para los usuarios de tu API. Esto significa decidir sobre las herramientas de descubrimiento, la experiencia del usuario y el público objetivo. A escala, también tendrás que decidir la coherencia de esta experiencia: si necesitas una gran coherencia, puede que tengas que centralizar las decisiones de diseño.

¿Cuándo y cómo se anuncian las API?

Comercializar una API tiene un coste de tiempo y esfuerzo, así que tendrás que decidir quién debe decidir cuándo comercializar una API. Puedes dejarlo en manos de equipos individuales de API, o puedes tomar esa decisión de forma centralizada. Si distribuyes la decisión entre tus equipos, tendrás que asegurarte de que las herramientas y procesos de descubrimiento centralizados no les impidan alcanzar sus objetivos de descubrimiento.

¿Cómo se mantiene la calidad de la experiencia de descubrimiento?

Con el tiempo, a medida que cambian las API, la información de cualquier sistema de detección se vuelve menos precisa. ¿De quién es la tarea de garantizar que el sistema de descubrimiento sea preciso? ¿Quién se asegurará de que la experiencia del usuario no se degrade a escala y con el paso del tiempo?

Gestión del cambio

Si nunca tuvieras que cambiar tu API, el trabajo de gestionar una API sería bastante fácil. Pero las API necesitan arreglarse, actualizarse y mejorarse, y siempre tendrás que estar preparado para cambiar la tuya. El pilar de la gestión del cambio incluye todas las decisiones de planificación y gestión que tendrás que tomar cuando te enfrentes al cambio. Es un ámbito de vital importancia y complejidad; de hecho, el pilar de la gestión del cambio es de lo que realmente trata este libro.

En términos generales, la gestión del cambio tiene tres objetivos:

• Elegir los mejores cambios

• Aplicar esos cambios lo más rápido posible

• Hacer esos cambios sin romper nada

Elegir los mejores cambios significa hacer cambios que permitan alcanzar los objetivos estratégicos de tu API. Pero también significa aprender a priorizar y programar los cambios en función de los costes, los contextos y las limitaciones. Ese es realmente el trabajo de gestionar un producto, y es una de las razones por las que introdujimos el concepto de API como producto en el capítulo anterior. Si estableces unos objetivos estratégicos claros e identificas a tu comunidad de usuarios objetivo, podrás tomar mejores decisiones sobre qué cambios son los más valiosos. A medida que aprendas más sobre el trabajo en cada uno de los otros nueve pilares, comprenderás mejor los costes. Armado con una buena información sobre el coste y el valor, podrás tomar decisiones inteligentes sobre el producto para tu API.

Equilibrar la seguridad del cambio con la velocidad del cambio es una propuesta difícil, pero es lo que tendrás que hacer. Cada una de las decisiones que tomas en los pilares de un producto API repercute en la velocidad o la seguridad del cambio. El truco está en intentar tomar decisiones que maximicen una con un coste mínimo para la otra. En los Capítulos 5, 7 y 8, profundizaremos en esta idea desde la perspectiva de los costes del cambio, los cambios realizados a lo largo del tiempo y el impacto de las organizaciones y la cultura en el cambio. Luego, en los últimos capítulos de este libro introduciremos una complejidad añadida: la escala. Los capítulos 9, 10 y 11 abordan la gestión del cambio para un panorama de APIs en lugar de una sola.

Implantar cambios es sólo la mitad del trabajo de la gestión del cambio. La otra mitad es hacer saber a la gente que tienen más trabajo que hacer porque has cambiado algo. Por ejemplo, si cambias un modelo de interfaz, probablemente tendrás que informar a tus diseñadores, desarrolladores y equipos de operaciones de que se les avecina un nuevo trabajo. Dependiendo de la naturaleza del cambio, es probable que tengas que informar a tus usuarios de que es posible que también tengan que actualizar su software cliente. La forma habitual de hacerlo es versionando tu API. La forma de versionar depende mucho del estilo de tu API y de los protocolos, formatos y tecnologías que utilices; hablaremos más de esto en "Versionado".

Decisiones clave para la gobernanza de la gestión del cambio

¿Qué versiones de deben ser rápidas y cuáles deben ser seguras?

Una decisión de gobierno importante es cómo tratar los distintos tipos de cambio. Si centralizas esta decisión, puedes crear una norma coherente que permita distintos procesos de liberación en función de su impacto. Algunos llaman a este enfoque "bimodal" o de "dos velocidades", pero nosotros creemos que hay más de dos velocidades en una organización compleja. También puedes descentralizar esta decisión y dejar que cada equipo evalúe el impacto por su cuenta. El peligro de descentralizar es que tus equipos no puedan evaluar con precisión el impacto en el sistema, por lo que tendrás que asegurarte de tener una arquitectura del sistema que sea resistente.

Utilizar juntos los pilares

Los pilares que hemos definido en este capítulo catalogan una enorme extensión de decisiones y esfuerzos. Pero no los hemos numerado, ni priorizado, ni puesto en secuencia, y eso es a propósito. Existen enormes variaciones en los métodos de entrega de proyectos y productos en las distintas organizaciones. Por tanto, queríamos ofrecerte una forma estructurada de definir las decisiones y el trabajo clave que tendrás que abordar de un modo que sea útil para cualquier método de desarrollo de software que te guste utilizar.

Pero uno de los problemas de compartimentar las decisiones y el trabajo en pilares es que pueden empezar a parecer categorías de trabajo distintas e independientes. En la práctica, casi nunca es así. En esta sección, exploraremos algunas de las formas más comunes en que los pilares de la API pueden utilizarse juntos para lograr los objetivos del desarrollo de productos API. Echaremos un vistazo a las formas en que determinados pilares se influyen mutuamente y a la perspectiva holística que deberás adoptar cuando los utilices. Más adelante, en el Capítulo 7, veremos cómo cambia la inversión en los distintos pilares a lo largo de la vida de una API.

Empecemos por ver cómo se utilizan conjuntamente los pilares de la API para afrontar los retos de planificar y diseñar una API.

Aplicar los pilares al realizar la planificación

En los últimos años, las fases de planificación y diseño han adquirido un poco de mala fama. A muchos implementadores les preocupa caer en la trampa del "Big Design Up Front" (BDUF), en la que un equipo pasa una cantidad desproporcionada de tiempo en una fase de diseño, totalmente desconectada de las realidades prácticas de la implementación. A medida que nuestro sector sigue adoptando los principios ágiles de, los métodos Scrum y la gestión Kanban, se ha puesto más énfasis en "hacer" y en un enfoque de probar y aprender. Creemos que esto es bueno.

Pero también sabemos que tiene un valor inmenso tener un objetivo claro, una estrategia coherente y un proyecto articulado que impulse la entrega. La necesidad de planificación y diseño es especialmente importante en un producto API. Esto se debe a que los cambios en cualquier interfaz siempre conllevan un coste. Todos hemos experimentado la frustración de tener que volver a aprender a hacer algo cuando una aplicación cambia su interfaz de usuario. Los cambios en las API pueden ser especialmente costosos, porque pueden afectar fácilmente al código de otra persona o incluso a todo su modelo de negocio.

Por eso, independientemente de tu metodología de entrega, merece la pena empezar con un plan claro para tu API. Según nuestra experiencia, incluso los equipos de API muy ágiles pueden beneficiarse de un poco de planificación previa. Para los productos API, es importante empezar en la dirección correcta y alinear el trabajo entre pilares con esa dirección. En concreto, hemos identificado tres áreas en las que hay que centrarse: alineación del diseño, creación de prototipos y definición de límites.

Pon a prueba tu estrategia y la alineación del diseño

Como mencionamos en "Diseño", es importante alinear tu estrategia y tu trabajo de diseño. El trabajo de dar vida a una API a través del diseño ("Diseño") y el desarrollo ("Desarrollo") implica un número increíblemente amplio de decisiones. Hemos visto que muchos profesionales tienen dificultades cuando no tienen un objetivo claramente definido al que dirigirse.

Para mejorar tu alineación, es importante contrastar continuamente tu diseño con tu estrategia. A medida que tomas decisiones de diseño e implementación, es fácil perder la perspectiva estratégica de tu trabajo. Tendrás que recalibrar poniendo a prueba las decisiones en función de tus objetivos estratégicos. Si has conseguido definir KPI u OKR, comprobar tus decisiones será mucho más fácil.

Comparación de dos estrategias: Twitter y Slack

Una comparación en de las aplicaciones de comunicación Twitter y Slack puede ayudar a iluminar cómo las decisiones que tomamos en estrategia pueden repercutir en todas las decisiones que tomamos en otros pilares. En "A Tale of 2 API Platforms", Jason Costa subraya el impacto que una dirección estratégica (o la falta de ella) puede tener en el desarrollo de un producto API. En concreto, destaca cómo Slack ha tomado decisiones intencionadas de diseño, desarrollo y gestión del cambio para impulsar sus objetivos estratégicos.¹ Contrasta este enfoque con la dirección estratégica más orgánica y volátil que adoptó Twitter, que según Costa ha provocado una ruptura potencialmente irrecuperable con los desarrolladores que utilizaban sus API.

Su estudio de caso pone de relieve una consideración importante para cualquier creador de API: las decisiones que tomamos dentro de un pilar estratégico probablemente tengan un impacto demoledor en todos los demás pilares en los que trabajamos.

Prototipo temprano

Los métodos modernos de entrega de software de hacen hincapié en la importancia de las iteraciones, los sprints y los lotes más pequeños de cambios. Según nuestra experiencia, éste es un elemento esencial para tener éxito con un producto API. Siempre que sea posible, realiza tu estrategia lo antes posible para poder probar su implementabilidad. Eso significa realizar el trabajo a través del desarrollo ("Desarrollo") y las pruebas ("Pruebas") incluso mientras se desarrolla tu estrategia.

Hay muchos nombres para este tipo de actividad de prueba y aprendizaje: prueba de conceptos, pilotos, "hilos de acero", MVP, etc. Lo llames como lo llames, el valor de la realización temprana es inmenso. De hecho, esta idea de mejora continua es un tema clave a lo largo de este libro.

Herramientas de creación de prototipos de API

Hace años, crear prototipos de una API significaba contratar a un ingeniero para que escribiera código personalizado. Pero, hoy en día, hay una gran cantidad de herramientas que pueden ayudar. Entre ellas se incluyen marcos como Spring Boot, que aceleran el trabajo tratado en "Desarrollo", permitiendo a los equipos crear rápidamente API prototipables y comprobables. Los equipos también pueden utilizar herramientas de diseño de interfaces para dar vida rápidamente al trabajo del pilar de documentación ("Documentación"). Existe un ecosistema cada vez mayor de complementos basados en la web y en IDE que pueden ayudarte a crear rápidamente una especificación de API. Algunas herramientas incluso permiten a los equipos crear rápidamente API a partir de un conjunto de datos o una base de datos existente. Te recomendamos que encuentres una herramienta que te ayude a centrarte en los aspectos de diseño y uso de tu API lo antes posible en las fases de diseño y planificación.

Definir los límites

En la práctica, tu producto API puede consistir en realidad en una colección de componentes individuales. Esto es especialmente evidente en el estilo de arquitectura de "microservicios" que se ha hecho cada vez más popular para las implementaciones de API. Como resultado, cada vez es más importante planificar con antelación los límites de los componentes para que puedas hacer realidad tu estrategia de producto API.

¿Qué es un microservicio?

En no existe una definición oficial y consensuada de microservicio. En su lugar, refleja un estilo de arquitectura basada en API que ha evolucionado en la década de 2010 a medida que han cambiado las tecnologías y las organizaciones. Casi todas las implementaciones de microservicios pueden caracterizarse por una descomposición de las aplicaciones en un conjunto de componentes habilitados para API que tienen el "tamaño adecuado" para aportar valor a una empresa.

En la práctica, esto significa que parte de tu trabajo de diseño para una única API se ha convertido en definir cómo se puede dividir esa API en múltiples piezas. Lo difícil de hacer esto bien es definir el conjunto adecuado de límites para tus componentes. Cada vez más, los equipos realizan su trabajo inicial de definición de límites con antelación, para poder construir componentes que estén mejor alineados con su estrategia.

Utilizar los Pilares para la Creación

Para dar vida a la estrategia API, tendremos que poner en práctica el producto API. En el Capítulo 7, exploraremos lo que significa realizar un producto API desde la perspectiva del ciclo de vida. Pero, antes de hacerlo, merece la pena considerar cómo se hará el trabajo real. Hasta ahora, hemos introducido cuatro pilares que son realmente importantes a la hora de crear una API: diseño, documentación, desarrollo y pruebas. Ahora, tenemos que explorar cómo puedes utilizar esos pilares juntos de forma valiosa.

Si tienes alguna experiencia en el desarrollo de software, sabrás que los pilares que hemos definido para construir una API no son exactamente nuevos ni novedosos. Todo el software que escribimos hoy en día -API o no- pasa por las etapas clásicas de diseñar, desarrollar, documentar y probar. También hay muchas metodologías de desarrollo de software que puedes utilizar para gestionar el trabajo en estos pilares. Por ejemplo, en, Kanban, Scrum y el Scaled Agile Framework están siendo adoptados por los profesionales como una forma de aplicar los principios ágiles a la entrega de productos. Estamos seguros de que tu organización tiene una forma establecida de construir software y de que podrás aplicarla a tu trabajo de ingeniería de software.

Pero una de las particularidades de las API es que encapsulan muchos conceptos diferentes en un único producto. Ya hemos hablado de ello antes en el libro, cuando presentamos el reto de comprender las interfaces, la implementación y las instancias ("Interfaz, implementación e instancia"). Tendrás que averiguar cómo aplicar los pilares creacionales del trabajo de API de forma que se unan esas partes. ¿Cómo diseñar, desarrollar, documentar y probar una API para que la interfaz y la implementación aporten el máximo valor estratégico?

Lamentamos decir que no existe un único enfoque milagroso para desbloquear ese valor. Pero la buena noticia es que hemos conseguido identificar tres enfoques que los profesionales han estado utilizando para tener éxito: documentación primero, código primero y pruebas primero. Echemos un vistazo a cada uno de ellos y comprendamos cuándo tienen más sentido.

Documentación primero

Cuando nos adentramos en los aspectos de ingeniería de las API, a menudo nos centramos en sus elementos tecnológicos: el código y la configuración que impulsan el comportamiento en tiempo de ejecución. Pero nada de esa actividad en tiempo de ejecución ocurre sin un desarrollador humano que trabaje en el código cliente que utiliza la API. Por eso algunos equipos adoptan un enfoque de "documentación primero" en su método de ejecución de la API.

Documentación primero significa que el equipo da prioridad al diseño de la interfaz humana de la API: la documentación. En lugar de empezar pensando en los aspectos técnicos de la implementación en Go, Java, NodeJS o cualquier otro lenguaje, se centran en documentar la API antes de que exista. Por ejemplo, al construir una API de pagos, podríamos empezar aplicando las decisiones y el trabajo del pilar de documentación ("Documentación") antes de escribir ningún código.

Una ventaja de hacer esto es que podemos probar la interfaz humana de la API antes de invertir en el trabajo de implementación que la acompaña. Por ejemplo, si escribimos una guía de uso y ejemplos para nuestra nueva API de pagos, podríamos probarla con un grupo de desarrolladores potenciales. Cambiar la documentación basándonos en sus comentarios será mucho más fácil que cambiar una implementación real de la API.

Pero, documentar primero no significa documentar únicamente. En la práctica, tiene sentido iniciar las actividades de "Desarrollo" y "Pruebas " mientras se ultima la especificación. Puedes ir un paso más allá desarrollando prototipos o "maquetas" de la API documentada, de modo que puedas ofrecer un producto vivo e invocable para pruebas tempranas.

La clave del enfoque "la documentación primero" es que basamos nuestras decisiones de implementación en la capacidad de aprendizaje, consumo y comprensión de la API. Es una buena técnica si quieres asegurarte de que tu equipo da prioridad al desarrollador consumidor en la fase de construcción. También es una buena forma de proporcionar los primeros entregables y activos a las partes interesadas no técnicas y a los patrocinadores.

Uno de los retos del enfoque de "documentar primero" es que puede dar lugar a productos que prometen demasiado y cumplen poco. Tienes que asegurarte de que las interfaces que se documentan sobre el papel puedan ser realizadas por los equipos de ingeniería que necesitan construirlas. En algunos casos, puedes estar construyendo sobre un complejo conjunto de capacidades descendentes que no pueden cambiarse. Cuando el estado objetivo aspiracional que se documenta es significativamente diferente de la realidad del ejecutor, el coste de construir la API puede ser abrumador.

Primero el código

El enfoque "code-first" de se centra primero en la complejidad de implementar las partes internas de la API. Eso significa que el equipo prioriza las actividades de "Desarrollo" y "Pruebas " para poder entregar rápida y eficazmente una primera versión de un producto API. Esto no significa que el equipo no proporcione documentación sobre la API, sino que el diseño documentado se ajustará a las decisiones tomadas durante la implementación, y no al revés.

El enfoque de "primero el código" es más útil cuando la velocidad de publicación pesa más que la consumibilidad y usabilidad de la API. Por ejemplo, los equipos que construyen microservicios suelen dar prioridad al trabajo de ingeniería porque no tienen previsto compartir su microservicio con otros equipos. En este caso, su atención puede centrarse en hacer que el código sea fácil de cambiar y liberar, más que en el consumo.

Este enfoque también puede ser útil para investigar y probar rápidamente la implementabilidad de un producto API como una "prueba de concepto" o un "pico tecnológico" para comprobar que se han identificado o mitigado todos los elementos de alto riesgo. Por ejemplo, un equipo de API puede empezar a escribir código para una API hipermedia o GraphQL como primer paso porque no está familiarizado con ese estilo concreto de API y necesita evaluar los aspectos prácticos del diseño.

Los equipos que dan prioridad al código pueden (y deben) seguir produciendo documentación para su interfaz. Dependiendo de la naturaleza del proyecto, esa documentación puede ser de naturaleza más ligera que la de un equipo documentation-first. Por ejemplo, los equipos code-first suelen documentar sus API con lenguajes de descripción de API legibles por máquina, como OpenAPI, en lugar de producir guías legibles por humanos. En algunos casos extremos, el equipo afirmará que el código es la documentación. Pero, el aspecto clave del enfoque "el código primero" es que el trabajo de documentación se centra únicamente en comunicar las decisiones de diseño que se han tomado durante la fase de codificación.

Como era de esperar, un enfoque de código primero puede proyectar fácilmente aspectos técnicos y de implementación en el diseño de la interfaz. Hacer que una API "code-first" sea más fácil de consumir para las personas ajenas a ella requerirá a menudo cambios en el código o la creación de otra API que se asiente sobre ella. Es importante tener en cuenta que si vas más allá del equipo u organización inmediatos, en un entorno controlado, este enfoque es difícil de mantener a largo plazo.

Prueba primero

Una variación moderna de del enfoque de "primero el código" y "primero la documentación" es la implementación de "primero las pruebas". En este tipo de desarrollo de API, se prioriza la comprobabilidad de la API por encima de su documentabilidad o implementabilidad. Este es una aplicación del Desarrollo Orientado a Pruebas (TDD) al ámbito de las API.

Desarrollo basado en pruebas

El concepto de Desarrollo Orientado a Pruebas fue popularizado por Kent Beck en su libro Test-Driven Development by Example. En la práctica, el TDD se aplica formal e informalmente de varias maneras. Pero el ingrediente clave es que el código destinado a la producción se diseña y fabrica de modo que pueda probarse.

Un enfoque de "primero la prueba" significa que el equipo de la API comienza creando casos de prueba que se ajustan a un estado objetivo deseado, seguido del trabajo de implementación para hacer que el caso de prueba pase. Para el desarrollo (ver "Desarrollo"), eso suele significar escribir pruebas que llamen a la API antes de escribir la API. Por ejemplo, al desarrollar una API de pagos, escribiríamos un caso de prueba para realizar un pago mediante una solicitud HTTP antes de escribir el código para gestionar y satisfacer la solicitud.

Las cosas se ponen más interesantes cuando consideramos el pilar de la documentación (ver "Documentación"). Como mínimo, adoptar un enfoque de desarrollo basado en pruebas significa que la documentación debe reflejar los casos de prueba que desarrollemos. En efecto, la creación de casos de prueba es la actividad de diseño de la interfaz. Pero, yendo más allá, algunos equipos están experimentando con formas de generar automáticamente documentación y ejemplos de código basados en los casos de prueba que se están escribiendo.

Empezar con pruebas es una forma fantástica de mejorar la comprobabilidad de un producto API. Esto conduce a cambios futuros más seguros y predecibles, porque el equipo confía en su capacidad para probar sus productos. Sin embargo, probar primero conlleva un coste de desarrollo adicional y puede retrasar el momento de la primera versión. En la práctica, muchos equipos adoptan un enfoque de "primero la documentación" para su producto API y un enfoque de "primero las pruebas" para el desarrollo.

Utilizar los Pilares para Operar y Dirigir

En las dos últimas décadas, ha aumentado la presión para crear software que pueda entregarse y modificarse rápidamente sin dejar de funcionar de forma estable, segura y fiable. Esto ha provocado cambios en la forma de desarrollar y utilizar el software. Las organizaciones están adoptando cada vez más culturas DevOps, ingeniería de fiabilidad del sitio y un enfoque DevSecOps que integra la seguridad en el proceso de desarrollo.

Desplazamiento de Operaciones a la izquierda

Hace años, era habitual que los desarrolladores escribieran una aplicación y luego la entregaran a un equipo de operaciones para que la ejecutaran y le dieran soporte. Pero, hoy en día, cada vez hay más interés en desarrollar aplicaciones de forma diferente. Los equipos que encarnan una cultura DevOps unen los mundos del desarrollo y las operaciones para que las aplicaciones se diseñen de forma que sean operables desde el principio. En muchos equipos de desarrollo modernos, las operaciones se han convertido en un ciudadano de primera clase en el proceso de desarrollo, en lugar de ser una ocurrencia tardía.

Aplicar este enfoque al desarrollo de API significa que los pilares de diseño, desarrollo, pruebas, implementación y monitoreo tienen que estar alineados. En la práctica, esto significa que los equipos tendrán que compartir la toma de decisiones y el trabajo que se realiza tanto en el pilar creativo como en el operativo. Un equipo de API que tome decisiones sobre herramientas y marcos de trabajo debe tener en cuenta tanto las preocupaciones de escribir código como las de implementación y ejecución.

En la práctica, la mayoría de las organizaciones acaban implantando una plataforma de herramientas de automatización DevOps que atienden las necesidades de los equipos de desarrollo de API. El objetivo de estas herramientas es acelerar el tiempo que se tarda en crear y modificar las API, mejorando al mismo tiempo su operatividad. Estas herramientas suelen permitir la estandarización y automatización de las tareas de prueba, implementación y monitoreo.

Por ejemplo, en el momento de escribir esto, una organización empresarial podría desplegar una plataforma DevOps con las siguientes herramientas:

Canalizaciones CI/CD

Una herramienta de mejora continua (IC) y entrega continua (CD) ² (CD) automatiza el proceso de prueba e implementación de un componente de software. En el ámbito de las API, las canalizaciones CI/CD se configuran a menudo para probar que una API no introducirá un cambio de última hora antes de su implementación en un entorno de producción. Este tipo de automatización de las pruebas y la entrega puede aplicarse a todos los entregables de tu producto API, incluidos los activos de diseño, la documentación y las implementaciones.

Contenedorización

Hoy en día, las API suelen implementarse como contenedores que pueden funcionar como unidades autónomas de implementación. Adoptar la contenedorización puede cambiar fundamentalmente la forma en que se implementan las API. Muchas organizaciones que empiezan a contenerizar sus API acaban introduciendo un enfoque de "microservicios" en el que dividen un producto API en piezas más pequeñas que pueden desplegarse de forma independiente.

Herramientas de observabilidad

Para ayudar a la supervisión y resolución de problemas, los equipos DevOps están implementando cada vez más herramientas que ayudan a la agregación, visualización e integración de los datos de registro y monitoreo. Para los equipos de API, esto significa que el trabajo de diseño y desarrollo debe adherirse a interfaces y formatos estandarizados, según determinen los equipos de DevOps. Un caso especial para los productos API es que las herramientas de observabilidad a menudo se extienden a los consumidores externos de una API. Por ejemplo, un portal para desarrolladores puede ofrecer análisis de uso y resolución de problemas a terceros que utilicen los productos API de una empresa.

Desplazamiento de la seguridad hacia la izquierda

Como mencionamos en el pilar de seguridad, las API presentan un tipo especial de superficie de ataque para los posibles malos actores. En particular, los implementadores de API deben tener en cuenta la mitigación de amenazas en los portales de documentación, el diseño de la interfaz, el almacenamiento de datos y la implementación del código. En los últimos años, han surgido tres patrones de seguridad que están cambiando la forma en que se trabaja en el espacio de las API:

Automatización DevSecOps

En, del mismo modo que las herramientas centradas en operaciones han influido en la forma en que se desarrollan las API, las herramientas centradas en la seguridad están teniendo el mismo efecto. Las organizaciones están incorporando cada vez más escáneres de vulnerabilidades en sus conductos CI/CD para que todos los cambios se inspeccionen rápida y eficazmente antes de implementarlos en producción. Por ejemplo, muchos equipos de API empresariales utilizan escáneres que comprueban las implementaciones de API frente a las amenazas OWASP. Hacer que este escáner de vulnerabilidades forme parte del proceso de codificación garantiza que los equipos aborden las vulnerabilidades de seguridad en una fase temprana del proceso de desarrollo.

Detección automatizada de amenazas

Hoy en día, las organizaciones no sólo comprueban pasivamente el código cuando se activan los escáneres, sino que escanean activamente los activos para encontrar vulnerabilidades y problemas. Ahora existe un saludable ecosistema de herramientas disponibles para ayudar a los equipos a monitorizar continuamente registros, repositorios de código, bases de datos e incluso APIs en vivo. Este tipo de monitoreo continuo de las amenazas ayuda a cambiar el comportamiento de los equipos de API, de modo que los problemas de seguridad se tengan en cuenta en una fase temprana del proceso de desarrollo.

Modelos de seguridad de confianza cero

Hace años, la mayoría de los modelos de seguridad dependían de la creación de un perímetro seguro para que se pudiera confiar en los sistemas situados dentro del perímetro. Pero, en los últimos años, Google ha contribuido a popularizar un modelo de "confianza cero" en el que no se debe confiar en ningún sistema basándose únicamente en su ubicación. Este cambio es el resultado de los modelos de organización e implementación cada vez más descentralizados asociados a la ingeniería de software moderna. Para los equipos de API, "confianza cero" significa que los creadores de API deben considerar cómo se aplicarán los controles de acceso como parte de su trabajo de diseño y desarrollo.

Plataformas de tiempo de ejecución

Introducir el trabajo de operaciones y seguridad de en los pilares de diseño, desarrollo y pruebas resulta tener un coste. Los equipos que tradicionalmente se centraban en escribir código ahora deben comprender aspectos detallados de los sistemas operativos, la infraestructura y la seguridad. Sin embargo, un conjunto emergente de herramientas y plataformas está ayudando a reducir algunos de estos costes.

Los equipos de API dependen cada vez más de las plataformas de tiempo de ejecución en las que se ejecutará su software. Esto se debe a que las plataformas modernas pueden manejar gran parte de la complejidad que surge de aplicar las preocupaciones de los pilares operar y ejecutar. Las herramientas, tecnologías y plataformas concretas que se utilizan cambian constantemente, pero en el momento de escribir esto, hay tres tecnologías que destacan por su gran impacto: Kubernetes, mallas de servicios y sin servidor.

Kubernetes

La estandarización de como unidad de implementación (por ejemplo, como contenedor "enviable") ha ayudado a muchos equipos a mejorar la forma en que operan y ejecutan sus API. Pero ejecutar un contenedor de forma segura y resistente en un entorno de producción sigue requiriendo mucha planificación y gestión cuidadosas. Por eso muchos equipos están incorporando la plataforma de orquestación de contenedores Kubernetes. Kubernetes proporciona una forma estandarizada de implementar, escalar, ejecutar y monitorizar una carga de trabajo de contenedores. Es atractivo porque significa que no necesitas dedicar tiempo a averiguar cuál es la mejor solución para realizar esas tareas: ya está hecho por ti. Pero desde la perspectiva de los pilares, es importante comprender cómo afecta esta decisión de Operaciones y Ejecución al trabajo de todos los demás pilares de la API. Cuando despliegues un componente de API en Kubernetes, tendrás que describir sus configuraciones de implementación, enrutamiento y escalado. Esto significa que el equipo que toma las decisiones de diseño, desarrollo y pruebas también debe conocer bien Kubernetes para poder crear un software que funcione. En teoría, asegurarse de que el equipo de desarrollo diseña y construye para los pilares de operar y ejecutar es una buena idea y abraza el espíritu de DevOps. Pero, ten en cuenta que en la práctica puede ser difícil (y caro) encontrar personas con una base de conocimientos tan amplia.

Malla de servicio

Ahora que se ha popularizado el estilo de microservicios, cada vez hay más productos de software compuestos por módulos de software y API más pequeños y estructurados. Pero, cuando descompones una API en piezas más pequeñas, haces más difícil el trabajo de cablear esas piezas de forma operable. Simplemente hay más cosas que gestionar. Para ayudar a gestionar estos costes, algunos equipos están incorporando un concepto de plataforma llamado malla de servicios. Una malla de servicios ayuda a reducir los costes operativos de la comunicación entre componentes de software a través de una red. La introducción de una malla de servicios suele conllevar un alto coste inicial de complejidad en los pilares de funcionamiento y ejecución, porque la mayoría de las herramientas de malla de servicios no son triviales de configurar, instalar y mantener. Pero una malla de servicios puede ofrecer grandes dividendos en los pilares de diseño y desarrollo, dando a tus equipos de API la libertad de construir unidades de implementación más pequeñas de forma que puedan ejecutarse con seguridad.

Sin servidor, código bajo y futuro

Un hilo común de en las innovaciones de plataformas en tiempo de ejecución para API es que nos ayudan a construir software altamente escalable y altamente resistente de forma más rápida y sencilla. La mayoría de las innovaciones que hemos visto lo hacen ocultando los costes de complejidad e introduciendo la estandarización. Esta tendencia continúa con la popularidad emergente de las arquitecturas "sin servidor", que ocultan toda la complejidad del funcionamiento de una plataforma tras una interfaz estandarizada y basada en eventos. Del mismo modo, la tendencia hacia las arquitecturas de "bajo código" oculta la complejidad de una arquitectura habilitada para API tras una interfaz de desarrollo estandarizada.

Los detalles de serverless, low-code, service meshes y Kubernetes están fuera del alcance de este libro. Pero, desde el punto de vista de la gestión de API, es vital que entiendas cómo afectan estas innovaciones de plataforma a las decisiones y al trabajo que gestionas en los distintos pilares. Por ejemplo, adoptar una plataforma sin servidor reduce en gran medida el coste y el alcance de tu pilar de desarrollo, pero introduce la necesidad de experiencia sin servidor en tus pilares de diseño, funcionamiento y ejecución.

Resumen

En este capítulo, hemos hecho un recorrido por los 10 pilares que forman la base del trabajo del producto API. En cada pilar residen las decisiones que repercuten en el producto API final. No todos los pilares requieren necesariamente el mismo esfuerzo de trabajo, y tendrás que decidir lo importante que es cada pilar en función del contexto y los objetivos de tu API. A medida que crezca tu panorama de API, también tendrás que pensar en cómo deben distribuirse las decisiones en cada uno de estos pilares. Hablaremos más de ello en el Capítulo 11. También hemos visto que algunos pilares funcionan en grupo, con más implicaciones y enredos de la práctica API en su conjunto. Ahora es el momento de comprender cómo gestionar el coste del cambio de las interacciones del ciclo de vida y cómo aplicar el nivel adecuado de inversión con el nivel adecuado de madurez para tu API.

Pero antes de llegar ahí, tendremos que explorar con más detalle nuestro 10º pilar, la gestión del cambio. ¿Cuál es el coste de realizar cambios en una API? Nos sumergiremos en ello en el próximo capítulo.

¹ Jason Costa, "A Tale of 2 API Platforms", Medium, 25 de octubre de 2016, https://oreil.ly/ZzAlj.

² O implementación continua.