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.

Transcript

1. Zdeněk Němec, superface.ai, October ‘23 AI-enabled APIs The next chapter superface.ai
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
3. We have been upgraded! superface.ai Prequel
4. APIs before 2023 superface.ai Chapter 1
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
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 ⚠
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
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
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….
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 🤞
11. Using AI to minimize the API plumbing superface.ai Chapter 2
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?
13. Comlink Communication link for APIs superface.ai Comlink handles the analysis of APIs and to connect your Application with APIs directly
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
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!
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 { … }
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: “joe@acme.com”, to: “ann@acme.com”, subject: “Hello world!” })
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: “joe@acme.com”, to: “ann@acme.com”, subject: “Hello world!” }) v1 v2 AI update mapping
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: “joe@acme.com”, to: “ann@acme.com”, subject: “Hello world!” })
20. AI-powered API documentation Best developer experience for your API superface.ai Your App comlink.playMusic({ room: “kitchen”, source: “…” })
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!
22. Do we have to know what API we use? superface.ai
23. Autonomous Agent superface.ai Chapter 3
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
25. Autonomous Agent Concept APIs are tools for AI superface.ai https://lilianweng.github.io/posts/2023-06-23-agent/ APIs!
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
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
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
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
30. Practical examples superface.ai considered solutions ChatGPT plug-ins RestGPT Superface Agent
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
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
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 edgar@superface.ai was Yesterday” superface.ai
34. Workflows Multi-step, complex, work fl ows in unknown or changing landscape superface.ai superface.ai
35. The road ahead superface.ai Chapter 4
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
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
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+
39. Thank you! Let’s talk! Zdenek “Z” Nemec 
 Twitter/X: @zdne LinkedIn: https://www.linkedin.com/in/zdne/ superface.ai superface.ai