Zdenek Nemec - Documentation, APIs & AI

This talk was presented at API The Docs Virtual 2023 Feedback, Metrics and Analytics event series on 25 January. We are glad to present the video recording, slide deck, talk summary, and the panel discussion below. Enjoy!

Visit the talk listing page for an overview of all presentations!

Zdenek Nemec

Founder and CTO at superface.ai

SaaS API integration fatigue

The need for API integrations grew in 80,4% of companies during the past few years, accelerated by the pandemic. Although, the average time needed by a SaaS app to build API integrations is approx. 700 days.

Why do integrations take so long?

In a typical integration process, where time and budget are distributed between analysis, development, testing, and deployment, analysis is always underestimated, and it always takes the longest time to finish.

Top six obstacles when integrating APIs

1. Understanding the API domain model and language. The user needs to do the mapping.
2. Answering the question “Can this API fulfill my use case”?
3. Understanding the ecosystem and documentation of the API vendor to integrate even a small functionality. The user needs to understand the system entirely.
4. Internal factor: the ambiguity of my own product requirements.
5. Quality of documentation, and outdated API specs.
6. Access hurdles, certification, API provider terms.

Aspects to analyze

• Business: Business rules, commercials, limits, regulations, certifications, SLAs. How can I integrate with the API and how much will it cost me?
• Product: What does the API offer, what are the API’s capabilities, and what use cases can the API fulfill?
• Implementation: How can I connect to the API, and what calls does the API use?

API documentation today focuses only on the wrong default: the implementation aspects, and it almost always neglects the other two. Although, the technical interface changes the most often.

What to do to minimize the analysis time?

With today’s tools: improve the API documentation

• Document the business and products aspects in addition to the technical reference
• Provide useful examples, SDKs, Postman collections
• Standardization & harmonization
• Unified APIs: “APIs in front of other APIs”

In the future: do next-gen API analysis

• Using an NLP-based (Natural Language Processing) augmented human operator that uses Large Language Models (LLM)/AI to assist you in the process of analyzing and integrating APIs.
• Improving machine-to-machine communication by creating self-integrating apps, so the applications could autonomously discover and connect APIs.

NLPs & APIs - evolution

• AI Client code gen: Github Copilot
• AI API interaction design: Jurassic-X
• AI API integration: OpenAI GPT-3/ChatGPT
• Superface's EDGAR

AI-enhanced API docs (API docs + NLP)

Imagine that you have an input field on an API documentation page where you can simply state your use case, then you receive an actual code that you can implement into your app.

What will the future of API documentation look like?

Focuses more on the product and business aspects instead of the implementation.

• Documents business models
• Explains the business models
• Focuses on use-cases

At this event, the presentations were followed by a panel discussion, where the speakers shared further thoughts and insights.

Panel discussion

Participants: Zdenek Nemec, Alvin Cho, Laura Vass.