The tide is rising, and AI is rapidly becoming an undeniable force shaping our world. As developers and owners of API programs, we can't afford to be caught off guard. Our APIs, the building blocks of interconnected systems, need to be ready to play a vital role in this AI-powered future.
Here's the challenge though: current API specifications like OpenAPI and AsyncAPI, while valuable, primarily focus on technical details. They lack the broader context that AI models and agents need. Imagine an AI model trying to navigate a city using only street maps – it might find its way around, but it wouldn't understand the landmarks, points of interest, or even the flow of traffic. This is where APIs.json steps in.
In computer science we have the notion of garbage in - garbage out. AI is perhaps the mother of all garbage in - garbage out cases, and we have all read horror stories that document this. But it doesn’t need to be so if we drive the process with high quality input data.
APIs.json: The Rosetta Stone for AI and APIs
Think of APIs.json as a universal translator, bridging the gap between your APIs and the world of AI. It's a structured data format that allows you to describe every facet of your API operation, from API specifications and functionalities to documentation links and support information.
You can check out the entire APIs.json data specification for yourself. Here we want to point out the core part of APIs.json, which has us very excited about the format: it is a set of properties with which you can describe each of your APIs, or alternatively the totality of your API operations.
"properties": [
{
"type": "Documentation",
"url": "https://example.com/documentation"
},
{
"type": "OpenAPI",
"url": "http://example.com/openapi.json"
},
{
"type": "JSONSchema",
"url": "http://example.com/json-schema.json"
}
],
In this example we have some of the expected properties and URLs pointing to documentation of each. However, the range of available properties is what makes APIs.json such a comprehensive data format, and it is extensible too.
Take a look:
|
Properties Elements: |
Contact Elements: | Maintainer Elements: |
|
* Swagger |
*Any vCard Element | * name * github * url *organizationName * organizationUrl * address * phoneNumber * image |
As you scan the properties list above, you have probably immediately spotted a number of properties that are useful to point to one or the other aspect of your API documentation. It is with these properties that you are able to express the full breadth and depth of your API operation as a whole and each of its APIs individually, and do it in a standardized and structured way.
what makes APIs.json a game-changer:
- Unmatched Comprehensiveness: Go beyond technical specs. Describe everything developers and AI agents might need, including getting started guides, tutorials, authentication methods, versioning details, contact information, and even links to community forums.
- Standardization into a Universal Language: APIs.json provides a common ground for both developers and AI to understand your APIs. This eliminates ambiguity and ensures everyone is on the same page, fostering smoother integration and interaction.
- AI-Friendliness at its Core: APIs.json empowers AI models to discover and comprehend your APIs with ease. This structured data acts as a roadmap, guiding the AI to the most relevant information and enabling it to learn and adapt to the real-world nuances of API usage.
The Benefits of Embracing APIs.json
The advantages of implementing APIs.json extend far beyond simply keeping pace with the AI revolution. Here are some key benefits you can expect:
- Revolutionize AI Model Training: Imagine training an AI model on a curated dataset of thousands of APIs described with APIs.json. This high-quality, standardized information would lead to a model that's not just trained on code, but also understands the context and practicalities of how APIs function in the real world. Compare this to how HuggingFace trained Meta’s general purpose Llama2 large language model with 70,000 chat conversations that resulted in Vicuña, a chat-enabled LLM that rivals GPT4 in accuracy.
- Streamline API Consumption by AI: APIs.json acts as a signpost for AI bots, directing them to the most authoritative, relevant and reliable information, which is curated by you and your team. This eliminates the risk of bots getting lost in a sea of low-quality data or outdated documentation. By ensuring AI agents have access to the right information, you empower them to leverage your APIs effectively and efficiently.
- Focus and improve AI models via Retrieval-Augmented Generation: APIs.json can form the top-level information in a Retrieval-Augmented Generation (RAG) architecture, where your API documentation is the source of truth to which the model is restricted. Using RAG, AI agents are able to link to their source information for quality assurance and audit purposes, and you can trust their output to be accurate and verifiable.
- Structured Information Architecture: APIs.json promotes a standardized information architecture across developer portals. This creates a consistent and user-friendly experience for AI agents, and of course also for developers, making it easier for everyone to find what they need, when they need it.
The Call to Action: Be a Leader in the AI-Powered Future
The future belongs to those who embrace change and drive innovation. By implementing APIs.json, you're not just making your APIs AI-ready, you're becoming a leader in shaping the future of AI-powered development. Here's how you can take action:
- Drive Cutting-Edge AI Development: Contribute to the advancement of AI by providing high-quality data for AI model training through APIs.json.
- Own Your Information Architecture: Don't let AI bots discover your content by chance. Use APIs.json to ensure they find the information you want them to find.
- Be Part of the Solution: Actively participate in shaping the future of AI-powered APIs. By adopting APIs.json, you send a clear message – you're ready to be a part of the solution, not a bystander left behind.
So I encourage you to gather all the pieces of your API program documentation into an APIs.json file and place this file into the root of your developer portal. Together we can take control of our future in the AI-powered world!
We are excited to announce that full APIs.json support for our customers is just around the corner, arriving in a few weeks! Additionally, a generic Drupal module for other Drupal-based developer portals is on the horizon, launching later this year. Stay tuned for further updates!
You can find the AI the Docs presentation below:
Sign up to our Developer Portals Newsletter so that you never miss out on the latest news, API documentation and Developer Experience research publications.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
