High-quality API documentation–technical and narrative both–in its canonical source of truth always was an obviously important need. However much we at Pronovix work in the midst of techie documentarians, we are certain that we clearly hear louder and louder demand to fulfill this need, at scale, pronto.
Like wildfire, our habits are changing in how we interact with information, and what we foresee is that–among others–developer portals should naturally be central sources of truth for integration interfaces: portals have to enable and reliably inform both human users and machine agents to navigate their increasingly complex ecosystems. Succinctly put: there is no AI without APIs, and APIs are by and large useless without their proper documentation.
This article draws on the keynote discussion at the 2024 DevPortal Awards Gala with Kristof Van Tomme CEO of Pronovix, Christoph Weber Solutions Architect at Pronovix and Laura Vass co-founder of Pronovix.
Platform portals, microportals, multiple gateways
In the past, developer portals were just a part of a gateway and/or an API management solution. But now there has been a shift towards looking at developer portals as a developer experience function that spans across your whole technology landscape, instead of having disconnected portals here and there.
Besides that, a new exciting direction we started thinking about, and we have seen a couple of examples in that direction, is a shift from developer portals as "a feature of your software infrastructure" towards either:
- A cross-company "platform-type portal", be that a marketplace or an interface- or digital solutions portal. This allows you to do experiments for different business products bundling digital interfaces together with product documentation, where you can also have detailed use case documentation that demonstrate and explain how these products can be used.
- A set of "microportals" for individual product focus areas or for specific ecosystem functions (e.g. a specific partner community, a vendor ecosystem for an important product). This fulfills a similar function but is focused on a customer/partner segment. These are more like traditional product marketing pages but with developer experience features that integrate the selection and the adoption processes of a digitally enabled solution.
The platform portal model already has some practical examples in use, whereas microportals are only just emerging.
From a technical perspective, the landscape has diversified significantly. Back in 2019, we saw one of the first examples from a major financial institution in the US adopting two gateways for their one developer portal, to meet multiple but distinct technical needs.
Since then, the approach of using multiple API gateways–or setting up multiple sub-organizations as separate, with the same gateway–is becoming common practice in the ecosystem. We have seen it with our customers and we have heard similar stories from friends and colleagues in the field. This is partially also necessitated by a much bigger spread to different APIs and different interfaces. According to the latest Gartner report, REST and SOAP APIs are holding strong, WebSockets and webhooks, Async APIs and graphQL APIs are prospected to gain much more usage, and especially gRPC is gaining momentum. There are many widgets, data contracts, and even homegrown protocols contributing to this diversity.
While all of this diversity is the result of progress, we should not burden the consumer with complexity, at least not in the initial phase of discovery and onboarding. Regardless of what is happening behind the scenes, there needs to be one touchpoint for your users to find exactly what they need and integrate where they need.
Break down gateway silos! Check out Pronovix's solution for one entry point for key provisioning, without proxies.
Developer portals for genAI
From conversations and surveys big and small, the need is clear for more and better software documentation. The core conclusion is that documentation is not becoming less important, but that it is indeed essential for successful software integrations. There might be a shift though, in who directly uses this documentation. We have to see how fast and how unevenly distributed this shift might be.
If you want to have well-structured, predictable results, you still might want to have a deterministic program that is consuming your APIs. Even if we get to Artificial General Intelligence and amazing autonomous robots; still we will need to be able to publish the interfaces that we provide both internally and externally. Authoritative, authentic documentation is what you want, no matter the means of integration.
The primary user persona might shift away from software developers and business integration people towards machine agents that consume your API documentation on behalf of a human user, potentially to establish even just a one-time connection. In the future, the wording “developer portal” might change since the portals will no longer solely serve developers. Although the name might be different, the function will still be needed all the same, and developer portals as a canonical source and centrally governed authentication media for integration information must actually become more and more important in a scenario of scaling up.
The interfaces you expose determine the role you play in the market. See our take on interface portals and the maturity dimensions we help portal teams follow.
Expose business affordances
Generative AI and the proliferation of private LLMs is actually accelerating the importance of developer portals by spotlighting the need for accurate, up-to-date, context-rich documentation. You need high-quality technical and narrative documentation to make your interfaces available for the technology systems searching for them. You have to make your business affordances (with programmatic interfaces) discoverable and findable so that both internally and externally people will actually be using those existing things. And hopefully the well governed APIs will also help to provide some guardrails around the capabilities you expose.
Regardless of the semantics, the underlying truth is that with AI in play now, the computer science notion of “garbage in, garbage out” has become more central and more important. The shining example in portals–whatever type of portals we call them–are the ones that focus on exposing business affordances and on use cases, rather than just the technical documentation. Because whatever automation will play later on, it is always about solving a use case.
And if you guide—whether humans, machines, or a mix—users through to how to achieve a goal, that is what the winning solution will be, no matter what. It is about pulling together multiple backends to multiple interfaces that are necessary, and documenting your step-by-step solutions.
Domain authority for your business
ChatGPT is starting to provide a competitor for using search engines as a general habit, but actually, if we take a closer look, gpts are basically running a world wide web-scale Retrieval Augmented Generation. The gpt first searches for the provided keywords, and then it generates its answer based on the content that is being loaded. This shift in how information is consumed and used amplifies the importance of publishing authoritative technical content and product documentation. Users are no longer forced to be sifting through tens of links. Instead, generative AI tools are selecting the sources to generate answers. As free ChatGPT answers in general lack source referencing at the end of 2024, the expectation of checking and quoting our references might fade out, and this will ripple far into the future of available content, infinitely diluted and misinformed.
Any of the generative AI models basically reflect back from what already exists. They are not inventing new tokens, although they may remix them in unexpected ways.
But even if users search through generative AI, you can still influence what people will see, indirectly. Domain authority is going to be the mechanism that allows your original documentation to be a business source of truth. Another mechanism is the model holding your way of thinking, but changing that is very hard albeit possible.
It is predictable that practical expertise and trustworthy knowledge will become statistically scarce and therefore very valuable. In the case of critical B2B integrations, authenticity is the precondition for trust relationships, even if mediated by machine agents in the first instance.
Conclusion
The emergence of sophisticated generative AI tools has sparked doubts and concerns about the future need of centrally maintained documentation and developer portals. But based on the current trajectory, authoritative documentation–technical and narrative both–is set to become instead more important than before. With machine agents directly consuming content to answer questions of human users or to set up integrations for them, accurate results can only be achieved with high-quality, unified interface documentation across your entire corporate landscape. This holds true both inside and outside of your organization.
Do you want to make sure that your developer portal is AI-ready? We can discuss your specific needs.
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.
