Upgrade to Pro — share decks privately, control downloads, hide ads and more …

AI-enabled APIs

Z
October 17, 2023

AI-enabled APIs

Keynote at Nordic APIs Platform summit, 17.10.2023
https://nordicapis.com/sessions/ai-enabled-apis/

Abstract
In 2023, AI entered the world of APIs, where human-centric API documentation plays a critical role. The fundamental job of API docs is to portray to its readers how the programmable interface works so they can instruct their applications to talk to each other.

And while AI/LLM processing API docs help greatly with integrating APIs, we are only at the beginning.

Let’s explore the emerging approach to employing AI in APIs, discuss its impact on integrating and building APIs, and see how changing our way of working with APIs leads to self-integrating applications.

Z

October 17, 2023
Tweet

More Decks by Z

Other Decks in Programming

Transcript

  1. Autonomous APIs • Pioneered the API- fi rst approach at

    Apiary.io → Oracle • Founder of API consulting Good API • Helped several Fortune 100 companies with their API strategy and execution
 • Founder and CTO of Superface.ai Zdeněk “Z” Němec superface.ai
  2. API Interface for sharing capabilities GET https: // wttr.in/stockholm?format=j1 200

    OK application/json Technical aspect Business aspect Weather forecast for Stockholm - location - temperature in Celsius - humidity - barometric pressure - uv indext - and more… superface.ai
  3. API Documentation The heart of APIs superface.ai • Instructions for

    engineers how to program API clients • Usually does poor job on documenting the business aspects of APIs • Raise and fall of API developer experience • When there is no API documentation there is no API Information about APIs are transferred “out-of-band” in form suitable to a human reader ⚠
  4. Tight coupling Welding client and server together Server Client GET

    https: // wttr.in/stockholm?format=j1 Server implementation hardcoded in client App superface.ai
  5. Analysis Development Testing Deployment time budget Expectation: Analysis Development …

    … Reality: superface.ai Typical integration project Finding the right API Capability I need? Costs? How to get access? What are the limitations? SLAs? How to use it? How it works? How to map my data model? Why is it not doing what I want? API consumer perspective
  6. API plumbing Manual labor needed to provide and consume capabilities

    👩💻 Design API 🦸 Document 👨💼 Publish 🙋 Discover 🤷 Try 👨💻📱 Implement Maintain 👨🔧 Build SDK 🧑💻 Purchase 👩💼 Test 👨💻 Test 👩💻 Implement 👨💻 API provider API consumer superface.ai All these people are needed to connect to programs together….
  7. Tools and processes for API plumbing Painkillers, not cure •

    API-design fi rst • OpenAPI, AsyncAPI, speci fi cation, Postman collections • “Better” API styles • Stripe-like API documentation • Better-than-Stripe API documentation All in the hope the API won’t change 🤞
  8. AI API analysis AI processing API documentation • Until now,

    API documentation was not accessible for machines • OpenAPI Speci fi cation, Postman collections are often missing, incomplete or vary in quality • AI-powered code generation for API integrations • pain point is NOT the development BUT analysis superface.ai considered solutions ChatGPT prompting GitHub Copilot Comlink (Superface) How to get business value out of an API using AI?
  9. Comlink Communication link for APIs superface.ai Comlink handles the analysis

    of APIs and to connect your Application with APIs directly
  10. 1. Index API documentation Prepare for machine processing # index

    API from plain text, readme.io, or OpenAPI Spec $ sf prepare https://resend.com/docs superface.ai
  11. 2. Describe your use case AI suggests business interface for

    your integration # create new Comlink for your use case $ sf new resend “send an email” superface.ai “Business case definition” usecase SendEmail { input { from to subject body } ... } sender Use your vocabulary!
  12. 3. Map use case to API AI fi gures out

    the technical aspects # figure out API calls for send email use case $ sf map resend send-email superface.ai POST https://api.resend.com/send content-type: application/json { … }
  13. 4. Execute the use case in your App Directly integrate

    API superface.ai Resend API Your App // Your App (pseudo code) comlink.sendEmail({ from: “[email protected]”, to: “[email protected]”, subject: “Hello world!” })
  14. • Your app is decoupled from the API: • API

    data model • API style • Media types • Endpoints Free to evolve Business aspect is the contract v2 Breaking API change superface.ai v1 Your App API comlink.sendEmail({ from: “[email protected]”, to: “[email protected]”, subject: “Hello world!” }) v1 v2 AI update mapping
  15. One use case, multiple APIs Business abstraction superface.ai # Index

    API documentations of different providers $ sf prepare https://resend.com/docs $ sf prepare https://docs.sendgrid.com/api-reference # Map use case to Resend API $ sf map resend send-email # Map use case to SendGrid API $ sf map sendgrid send-email Resend API Sendgrid API Your App comlink.sendEmail({ from: “[email protected]”, to: “[email protected]”, subject: “Hello world!” })
  16. AI-powered API documentation Best developer experience for your API superface.ai

    Your App comlink.playMusic({ room: “kitchen”, source: “…” })
  17. superface.ai • Integrate many APIs quickly • Not bother with

    API docs • API client resilient to changes • We don’t even have to know the API style and endpoints!
  18. Autonomous (API) Agent Your App as Autonomous Agent Autonomy: freedom

    from external control or in fl uence; independence Agent: a person who acts on behalf of another person, the doer of an action A software that acts on behalf of its user, that is free* to make decisions. superface.ai
  19. Autonomous API Agent • No hardcoded API calls • Decides

    at runtime what API to connect to • Figures out at runtime how to connect API API Agent Registry I am here, and this is how agents connect I need to send email. What tool (API) is available? Here are the APIs and how to connect API Communication superface.ai
  20. Set of tools: API landscape Agent Inventory 1 Inventory 2

    Orders CRM PLM Agent is takes a use case, GET https: // 192.12.13.1/service/ inventory?pid=12355 “Check inventory” not an API Use cases, not APIs superface.ai Boundary within agent navigates
  21. Multiple API landscapes Network of capabilities Stripe Azure Ayden Twilio

    Google Fedex … Global Landscape Global capabilities Partner organization Service 2 Service 1 Service 3 Agent CRM Inventory 2 Orders Inventory 1 PLM Organization landscape Partner capabilities superface.ai
  22. AI-ready APIs • LLMs have limited context size (2k, 4k,

    8k, 16k, rarely 32k) • Bloated API design ❌ • Number of APIs it can consider ❌ • The quality of API docs & specs • Most agents don’t handle other styles but RESTful superface.ai • RESTful – HTTP JSON API • Use-case focused design • Bundle calls together • Consider limiting functionality • Concise data model • return only what is absolutely needed • Minimize OAS, YAML format • De fi ned data model (JSON Schema) • Skip examples :( Current agent limitations API design practice for AI API design for autonomous agents
  23. Navigation in a landscape Unknown or changing landscape of capabilities

    and providers Hub Autonomous Agent "Who can tell me about inventory?” List of available inventory services “What is the inventory for our product?” “The inventory for is 42” Internal inventory services superface.ai
  24. Provider selection The right capability and provider for the task

    Price, quality and relevancy… “Send “Greetings from Jane” to +38553694008” Infobip API Based on con fi guration, price, and country auto agent uses Infobip “Your message has been sent” superface.ai
  25. Personal assistant Your landscape unique to you Autonomous agent decides

    what of the available email services to use based on its con fi guration and your identity… “When was the last email from Edgar?” Gmail API Based on Hub con fi guration auto agent will ask Gmail “The last email from [email protected] was Yesterday” superface.ai
  26. The future of AI and APIs We are only at

    the start • AI API Analysis is powerful but still just a pain killer • Agents need only the business aspects of API • they can fi gure out the REST (pun!) • We need to surface the business of APIs but not the implementation • Human-centric API documentation in the future? superface.ai
  27. Machine to machine • Human documentation will document the business-aspects

    only • APIs will provide machine-readable metadata for agents directly: • Communication protocol • technical aspects of the API implementation • Business protocol • description of capabilities • commercial details including SLAs • legal aspects superface.ai
  28. Road ahead Towards machine-to-machine APIs superface.ai human-centric APIs machine processing

    of human-centric APIs 2023 fi rst self-describing APIs, hybrid human & machine 2025 machine-only APIs 2030+
  29. Thank you! Let’s talk! Zdenek “Z” Nemec 
 Twitter/X: @zdne

    LinkedIn: https://www.linkedin.com/in/zdne/ superface.ai superface.ai