API The Docs Virtual 2023 Feedback, Metrics and Analytics Recap
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!
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
Understanding the API domain model and language. The user needs to do the mapping.
Answering the question “Can this API fulfill my use case”?
Understanding the ecosystem and documentation of the API vendor to integrate even a small functionality. The user needs to understand the system entirely.
Internal factor: the ambiguity of my own product requirements.
Quality of documentation, and outdated API specs.
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
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.