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. Zdeněk Němec, superface.ai, October ‘23
    AI-enabled APIs
    The next chapter
    superface.ai

    View full-size slide

  2. 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

    View full-size slide

  3. We have been upgraded!
    superface.ai
    Prequel

    View full-size slide

  4. APIs before 2023
    superface.ai
    Chapter 1

    View full-size slide

  5. 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

    View full-size slide

  6. 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

    View full-size slide

  7. Tight coupling
    Welding client and server together
    Server
    Client
    GET https:
    //
    wttr.in/stockholm?format=j1
    Server implementation
    hardcoded in client App
    superface.ai

    View full-size slide

  8. 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

    View full-size slide

  9. 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….

    View full-size slide

  10. 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 🤞

    View full-size slide

  11. Using AI to minimize the API
    plumbing
    superface.ai
    Chapter 2

    View full-size slide

  12. 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?

    View full-size slide

  13. Comlink
    Communication link for APIs
    superface.ai
    Comlink handles the analysis of APIs and
    to connect your Application with APIs
    directly

    View full-size slide

  14. 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

    View full-size slide

  15. 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!

    View full-size slide

  16. 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
    { … }

    View full-size slide

  17. 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!”
    })

    View full-size slide

  18. • 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

    View full-size slide

  19. 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!”
    })

    View full-size slide

  20. AI-powered API documentation
    Best developer experience for your API
    superface.ai
    Your App
    comlink.playMusic({
    room: “kitchen”,
    source: “…”
    })

    View full-size slide

  21. 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!

    View full-size slide

  22. Do we have to know what API we
    use?
    superface.ai

    View full-size slide

  23. Autonomous Agent
    superface.ai
    Chapter 3

    View full-size slide

  24. 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

    View full-size slide

  25. Autonomous Agent Concept
    APIs are tools for AI
    superface.ai
    https://lilianweng.github.io/posts/2023-06-23-agent/
    APIs!

    View full-size slide

  26. 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

    View full-size slide

  27. 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

    View full-size slide

  28. 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

    View full-size slide

  29. 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

    View full-size slide

  30. Practical examples
    superface.ai
    considered solutions
    ChatGPT plug-ins RestGPT Superface Agent

    View full-size slide

  31. 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

    View full-size slide

  32. 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

    View full-size slide

  33. 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

    View full-size slide

  34. Workflows
    Multi-step, complex, work
    fl
    ows in unknown or changing landscape
    superface.ai
    superface.ai

    View full-size slide

  35. The road ahead
    superface.ai
    Chapter 4

    View full-size slide

  36. 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

    View full-size slide

  37. 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

    View full-size slide

  38. 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+

    View full-size slide

  39. Thank you!
    Let’s talk!
    Zdenek “Z” Nemec 

    Twitter/X: @zdne

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

    superface.ai
    superface.ai

    View full-size slide