Las encuestas recientes apuntan a un crecimiento masivo en bots impulsados por la IA arrastrando Internet en busca de API. Si bien muchos de estos tienen intención maliciosa, un número creciente son consumidores de API bien intencionados que solo intentan descubrir, consumir y beneficiarse de las API existentes. Y, cada vez más, estas solicitudes de API provienen de plataformas impulsadas por MCP (protocolos de contexto modelo) diseñados para permitir que el software autónomo interactúe directamente con las API web y, si las estadísticas recientes son una guía, están luchando. La tasa de éxito para los flujos de trabajo API impulsados por la IA de varios pasos es de aproximadamente el 30%. Peor aún, estos clientes a menudo no se rinden. En cambio, siguen intentando, y fallando, interactuar con sus API, aumentar el tráfico mientras reducen la propuesta de valor general de las API objetivo. ¿Qué está pasando aquí? ¿Por qué los clientes impulsados por la IA no pueden aprovechar las API de hoy? ¿Y qué se necesitará para cambiar esto? Resulta que la respuesta ha estado allí todo el tiempo. Las cosas que los consumidores de API impulsados por la IA necesitan son las mismas cosas que los desarrolladores humanos necesitan: claridad, contexto y estructura significativa. Sin embargo, muchas empresas todavía no están prestando atención. Y, como aprendimos en 2017, «la atención es todo lo que necesitas». ¿Estás prestando atención? El histórico documento de 2017 «La atención es todo lo que necesitas» introdujo el mundo en la noción de transformadores. En el mundo de la IA, un transformador es un modelo donde las palabras se califican matemáticamente en función de sus relaciones con otras palabras en el contenido circundante. Esta puntuación, denominada atención, hace posible que los programas que usan transformadores (como ChatGPT) producen respuestas que se sientan notablemente coherentes a los lectores humanos. La capacidad de usar transformadores para impulsar herramientas generativas de IA hace que sea imperativo que todos repensemos la forma en que diseñamos, documentan e implementamos nuestras API. En pocas palabras, los transformadores prestan atención a todo el contenido al que tienen acceso, pero no entienden nada de eso. Aún más al punto, las plataformas Genai como ChatGPT, Claude, Gemini y Copilot pueden prestar atención fácilmente al diseño de su API. Pueden identificar las URL, los métodos HTTP, las entradas, el esquema y las salidas esperadas. Pero no pueden realizar ningún razonamiento sobre qué API usar y lo que realmente significa el contenido en el cuerpo devuelto. Esencialmente, los bots de hoy en día son consumidores de API rápidos y flexibles que no pueden salir de una bolsa de papel húmedo. La buena noticia es que podemos aprovechar las habilidades de un cliente impulsado por la IA para prestar atención y agregar apoyo dentro de nuestro diseño de API para compensar su incapacidad para tomar decisiones sabias. Y esa es una receta clara para hacer que sus API AI-listas. Las aplicaciones de GAPS LLM tienen con respecto a la toma de decisiones, el significado y la comprensión. Below son cuatro prácticas que ya sabemos que hacen que sea más fácil para los desarrolladores humanos comprender y usar nuestras API. Resulta que estas son las mismas cosas que ayudarán a los clientes de API impulsados por la IA a tener más éxito también. Sea explícito: no asuma que los clientes comprenden lo que esta API les diga por qué: proporcione descripciones claras de por qué y cuándo los clientes pueden usar la apibe consistente: cuanto más se parezca su API que se parece a los miles de otros en los datos de capacitación de la LLM, más respuestas de error de los trabajos procesables: proporcione la retroalimentación más fácil, consistente y más fácil de resolver los errores de ejecución de la mirada a la mirada de cada uno de estos en el turno. Exploradores. Si bien son excelentes para analizar el texto y hacer asociaciones, las máquinas no hacen saltos intuitivos. En cambio, las máquinas necesitan posibilidades explícitas; Pistas sobre lo que se puede lograr, cómo hacerlo y por qué es posible que desee ejecutar una acción. El enfoque clásico centrado en el ser humano de diseñar y documentar una API se captura en esta lista de breve: get /científicas /get /científicas /{id} post /científicas /put /clients /{id} delete /clientes /{id} La mayoría de los humanos saben exactamente lo que esta lista se comunica; La lista completa de operaciones disponibles para administrar una colección de registros de clientes. Los humanos buscarían en otros lugares en la documentación de diseño de API para determinar las propiedades de datos requeridas y opcionales para pasar por cada acción, así como el formato para lanzar las interacciones (JSON, XML, HTML, etc.). Pero no se puede confiar en las máquinas para exhibir ese nivel de comprensión y curiosidad. Es más probable que hagan algunas «conjeturas estadísticas» sobre lo que representa esta tabla y cómo usarla. Para aumentar las posibilidades de éxito y reducir la probabilidad de errores, es mejor ser mucho más explícito en su documentación de API para máquinas. Como en el siguiente ejemplo de documentación que está ajustado para el consumo de LLM: para recuperar una lista de registros de clientes, use get /clientes /para recuperar un solo registro de clientes use get /cientats /{id} mientras proporciona el valor adecuado de {id} para crear un nuevo registro de clientes. {id} para eliminar un registro de clientes de la colección use Eliminar /{Id}} Al proporcionar el valor adecuado para {id}, mientras que estas dos listas esencialmente tienen el mismo significado para los humanos, la segunda lista es mucho más útil para los clientes de API de la máquina. Otra forma en que puede hacer esto es proporcionar detalles sobre por qué un cliente API podría querer usar un punto final de API en particular. Es importante tener en cuenta que los clientes impulsados por la IA son bastante buenos para adivinar cómo se puede usar una API, pero estos mismos LLM no son muy buenos para descubrir por qué deberían usarse. Puede arreglarlo agregando texto que explique los usos comunes para cada punto final de la API. Por ejemplo, en su documentación, incluya frases como «Use el punto final de PriorityAccounts para identificar a los diez principales clientes en función del tamaño del mercado». O «Use el punto final SubtitApplication una vez que se hayan completado todos los demás pasos en el proceso de solicitud de empleados». Estas descripciones proporcionan sugerencias adicionales a los consumidores de API sobre por qué o incluso cuándo las API serán más útiles. Note que, en ambos casos, el texto identifica el punto final por su nombre y explica la razón por la cual un cliente API podría usar esa API. Los clientes de IA, especialmente los respaldados por LLMS, son muy buenos para reconocer un texto como este y asociarlo con otro texto en su documentación, como la lista que revisamos en la sección anterior. Predictar el poder real detrás de las aplicaciones de clientes basadas en LLM se encuentra en todos los documentos y codificamos estos modelos de lenguaje que han recogido como datos de entrenamiento. Todos los libros, documentos y código fuente alimentados en bases de datos LLM proporcionan un contexto estadístico para cualquier texto nuevo que proporcione su documentación de API. Es el esfuerzo histórico acumulado de miles de escritores, programadores y arquitectos de software lo que hace posible que los clientes de IA interactúen con su API. Y esas interacciones serán mucho más suaves si su API se parece mucho a todas esas otras API que se alimentó como datos de capacitación. Si su diseño de API contiene muchos elementos únicos, respuestas inesperadas o uso no tradicional de protocolos comunes, las aplicaciones impulsadas por IA tendrán un momento más difícil interactuar con él. Por ejemplo, mientras es perfectamente «correcto» para usar HTTP para crear nuevos registros y parche HTTP para actualizar los registros existentes, la mayoría de las API de HTTP usan la publicación para crear registros y actualizarlos. Si su API se basa únicamente en una forma única de usar las operaciones PUT y Patch, probablemente esté haciendo las cosas más difíciles en sus aplicaciones impulsadas por IA y reduciendo sus posibilidades de éxito. O, si su API depende exclusivamente de un conjunto de documentos de definición de esquema basados en XML, los clientes de API a IA que han sido capacitados en miles de líneas de esquema JSON podrían no reconocer sus objetos de entrada e entrada de API y podrían cometer errores al intentar agregar o actualizar datos para su API, cuando sea posible, aprovechar los patrones comunes y los detalles de implementación cuando creen su API. Eso asegurará que los clientes de IA puedan reconocer e interactuar con éxito con sus servicios. Respuestas de error que se pueden accionar cuando los humanos encuentran errores en las interfaces de usuario, generalmente pueden escanear la información de error mostrada, compararla con los datos que ya escribieron y aparecen una solución para resolver el error y continuar utilizando el servicio. Eso no es muy fácil para manejar los clientes de API impulsados por la máquina. No tienen la capacidad de escanear la respuesta inesperada, derivar significado y luego formular una solución creativa. En su lugar, lo intentan nuevamente (tal vez con algunos cambios aleatorios) o simplemente se rinden. Cuando diseñen sus API para admitir clientes impulsados por la máquina, es importante aplicar las mismas tres reglas que ya hemos mencionado (sea explícito, dígales por qué y ser predecible) cuando los clientes de API encuentren errores. Primero, asegúrese de que la aplicación del cliente reconozca la situación de error. Para los clientes de API, esto es más que solo devolver el estado HTTP 400. También debe incluir un documento formateado que identifique y explique los detalles del error. Una excelente manera de lograr esto es utilizar los detalles del problema para el formato de especificación de APIS HTTP (RFC7078). Esta respuesta le brinda una forma estructurada de identificar el problema y sugerir un posible cambio para resolver el error. Nota que esta respuesta también cumple con nuestros criterios para la segunda regla (dígales por qué). Esta actualización falló porque faltaba un campo y ese campo es Hatsize. El informe de error incluso le dice a la máquina lo que pueden hacer para hacer otro intento de actualizar el registro. Otra ventaja de usar el formato RFC7078 es que nos ayuda a cumplir con la tercera regla (sea consistente). Este RFC es una especificación común que se encuentra en muchos ejemplos de API y es muy probable que los datos de entrenamiento de la LLM contengan muchas de estas respuestas. Es mejor usar este formato de error existente en lugar de confiar en uno que creó usted mismo. Finalmente, es una buena idea diseñar sus API para tratar los errores como intentos parciales. La mayoría de las veces, los errores de API son simplemente errores simples causados por documentación inconsistente o faltante y/o desarrolladores inexpertos. Proporcionar información de error explícita no solo ayuda a resolver el problema más fácilmente, sino que ofrece la oportunidad de «volver a entrenar» a los clientes a la máquina al poblar el contexto local de la máquina con ejemplos de cómo resolver errores en el futuro. Los clientes recorreos, recordados, LLM son excelentes para reconocer los patrones. También puede usar eso cuando diseñe sus API. Para resolver su problema inmediato. Velorarlos por qué hace que sea más fácil para los desarrolladores identificar las API que necesitan y comprender mejor la forma en que funcionan y cuándo pueden aplicarse. Ser consistente es otra forma de reducir la carga cognitiva para los programadores y proporcionar una experiencia más «intuitiva» cuando se usa su API.and, lo que hace que las respuestas de error tengan un mejor error de errores a la retroalimentación de errores y más consistentes en el tiempo de ejecución y el tiempo de diseño en el tiempo de diseño. En el camino, los clientes de API (tanto humanos como a la IA) usan su servicio. Tome nota de qué puntos finales se usan comúnmente. Identifique las condiciones de error persistentes y cómo se resuelven. Y realice un seguimiento del tráfico de clientes de API como una forma de medir qué API proporcionan la mayor retorno para su esfuerzo y cuáles son más problemas de los que valen. El monitoreo de calidad de sus API lo ayudará a comprender mejor quién las está usando y qué tipo de problemas están teniendo. Eso le dará pistas sobre cómo puede rediseñar sus API en el futuro para mejorar la experiencia para todos. Si está apoyando el consumo de API impulsado por los humanos o clientes impulsados por la máquina, prestar atención puede dar sus frutos generosamente.