Slide 1

Slide 1 text

Zdeněk Němec, superface.ai, October ‘23 AI-enabled APIs The next chapter superface.ai

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

We have been upgraded! superface.ai Prequel

Slide 4

Slide 4 text

APIs before 2023 superface.ai Chapter 1

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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 ⚠

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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 🤞

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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?

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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!

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

• 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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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!

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

Autonomous Agent superface.ai Chapter 3

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

The road ahead superface.ai Chapter 4

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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+

Slide 39

Slide 39 text

Thank you! Let’s talk! Zdenek “Z” Nemec 
 Twitter/X: @zdne LinkedIn: https://www.linkedin.com/in/zdne/ superface.ai superface.ai