Building on my thoughts around the evolution of API documentation from a couple weeks back I repeatedly find myself questioning whether the current notion of the API portal will be able to keep pace with the API velocity in most enterprise organizations. I think the notion of the API portal that has been spoon fed to use by API management providers over the last decade has it’s place in providing a single place to find the public APIs within a domain, but this isn’t too for all organizations, and then when you combine with the microservices expansion internally, partner APIs needed to support integrations, and the growing number of SaaS APIs used to power our business, the concept of an API portal begins to fall apart pretty quickly.
You can see what I am talking about present in the concept of the OpenAPI. Most OpenAPIs, which are customarily published to a portal to power documentation, do not keep up with the pace of change that is actually occurring on the ground within organizations. You see this reality being addressed by a new wave of startups like Optic and Akita Software. Developer relations, experience, and documentation teams are barely able to keep up with the changes occurring across APis, and aren’t always able to keep documentation reflecting the true surface area of their APIs. Teams are feeling this strain when it comes to their public APIs, but is something that begins to completely fall apart when trying to ensure that all internal microservices have an OpenAPI, are properly described, and published to an internal portal. From what I am seeing, we have to just give tools to our developers that don’t add the extra work of maintaining the traditional notion of a portal, and just give them documentation, code samples, SDKs, examples, client solutions, and the other things present in a portal by default.
API developers need to just be able to focus on the value generated by the API, and the old traditional road to making each API available via a single portal should just come for free. Their APIs should be immediately available via search, with the required RBAC, privacy, and other security controls in place. They should be published to private, team, partner, and public portals, networks, and hubs as part of the natural development lifecycle. The modern portal should come to the API developer, not the other way around. I also question whether the notion of a portal even matters going forward, and each API, and it’s derivative mocks, document, tests, and monitors should just be embeddable and linkable in any documentation, blog posts, social media, or existing communication channel. I really don’t want to have the extra step of having to go to a portal to find what I need, I need my API stop just come to me via my existing services, tools, and communication channels. Leaving me feeling like the classic notion of an API portal won’t be able to keep up with the ever expanding world of APIs.
