Map Your Api Landscape To Prevent Agentic Ai Disaster

For complete 15 years, Kin Lane, co-founder and main organization serviceman (CCO) for unfastened root API instauration Naftiko, has been building his expertise successful APIs — not only nan method specifications but besides nan business angle. He believes that nan increasing usage of copilots and agentic AI systems successful enterprises intends we must creation and build APIs astir business capabilities alternatively than resources. APIs should correspond halfway business functions for illustration “manage inventory” aliases ”process payments,” he says.

He is not unsocial successful this view. Multiple different well-known API experts, including Christian Posta, Mike Amundsen and Daniel Kocot, person reached akin conclusions.

Recent investigation documented successful DORA’s “State of AI-Assisted Software Development Report” provides support for this perspective, concluding that generative AI (GenAI) is an amplifier. “It magnifies nan strengths of high-performing organizations and nan dysfunctions of struggling ones,” nan study states. Lane sees that amplification effect successful organizations’ approaches to nan APIs they build and consume.

“Companies will win aliases neglect successful their AI implementations based connected their existing API finance and really acold they are on their API journey,” he told maine successful an interview. “For example, do they person an API catalog? Do they person unfastened APIs? Are they testing/mocking? Are their APIs decently documented? Are they invested successful unfastened source?”

The AI programs of organizations pinch an immature attack to APIs will, Lane believes, beryllium a disaster. With that successful mind, Lane outlined a four-step process for getting a grip connected your API scenery for a much successful AI implementation.

1. Map Your API Landscape

The logic for this imaginable nonaccomplishment pinch APIs is that less-mature organizations person “a large spread betwixt what an endeavor knows and what it is tin of,” Lane said. The mean enterprise’s Software arsenic a Service (SaaS) portfolio is astir 250 to 500 services, each of which person APIs. But, according to Lane, pinch constricted intends of discovery, galore extremity up hardly used.

Introducing an AI supplier into this situation will nutrient 1 of 2 outcomes: Either nan supplier can’t observe nan APIs that are disposable to it, truthful it’s reasonably useless. Or it tin entree those APIs but ends up oversharing, exposing information that should beryllium kept private. Therefore, nan first privilege must beryllium building a representation of nan organization’s API scenery to understand some nan soul and outer resources.

Building this representation requires looking astatine nan disposable signals. If you were building an API representation of an statement from nan outside, you would look astatine nationalist GitHub repos, blog posts, property releases, occupation listings and immoderate tech docs for published APIs. The aforesaid process tin beryllium utilized internally, thing Lane became acquainted pinch erstwhile he led API governance astatine Bloomberg for a year.

“I crawled GitHub and Confluence, looking for immoderate beingness of an API. I mapped that landscape, figured retired nan teams down it and organized nan information into an org floor plan that became for illustration my chessboard,” Lane said.

2. Develop a Ubiquitous Language

With this representation successful place, Lane’s 2nd privilege is to look astatine nan connection utilized wrong nan components of an API, specified arsenic endpoint URLs, method names and parameters.

Netscape Principal Developer Phil Karlton famously said, “There are only 2 difficult things successful machine science: cache invalidation and naming things.” Naming things is challenging because nan connection choices we make really matter. While language is chiefly a instrumentality for connection alternatively than thought, connection influences attention, representation and categorization, making definite cognitive distinctions easier aliases harder and perchance obscuring intended meaning.

Bloomberg’s APIs were chiefly REST APIs. “The APIs I reviewed each had words for illustration ‘database’ aliases ‘ERP’ successful their names,” Lane said. “This isn’t bully design.”

Lane discovered that successful nan immense mostly of cases, Bloomberg developers build APIs astatine nan incorrect level of abstraction, mirroring backend systems alternatively than business processes. This manifests successful API sprawl and aggregate APIs that service nary existent purpose.

This isn’t a limitation of REST, but utilizing REST does style our thinking: It encourages america to attraction connected nan representational authorities transportation of resources, since that is what REST was designed to handle.

“I’d opportunity 90% of group don’t do REST API creation well,” Lane said. “They don’t deliberation aliases attraction astir REST, and they don’t return a consumer- aliases product-oriented attack to design.”

The measurement REST shapes our reasoning is 1 illustration of really connection choices matter. REST’s verbs — GET, PUT, PATCH, DELETE — specify an action to beryllium performed connected a peculiar assets (or a postulation of resources). For immoderate API, nan vocabulary shapes nan reasoning of nan developers who usage it. An API is, successful effect, a mini connection that its consumers person to learn. The names we take shape our intelligence model, arsenic Harry Richardson, main intelligence astatine SoftIron, told maine successful 2024.

A consequence is that taxonomy is important. Taking a leafage retired of Eric Evans’ book “Domain-Driven Design,” Lane suggests that developers request to commencement by building a communal aliases “ubiquitous” connection that’s shared betwixt IT and nan remainder of nan business. This is simply a bully thought that’s seldom executed.

“Enterprises move truthful accelerated that you extremity up pinch a messy connection crockery of invoices, payments and messages that don’t stock nan aforesaid discourse aliases activity together,” Lane said.

Moreover, erstwhile domain experts and developers don’t stock a communal language, connection breaks down successful costly ways. Experts usage specialized terminology from their field, whereas developers deliberation successful method abstractions, creating a linguistic spread wherever some sides only vaguely understand each other. Even erstwhile a fewer squad members span this divide, they go accusation bottlenecks, and their translations suffer precision — resulting successful muddled concepts, changeless misinterpretation crossed nan squad and yet codification that gets refactored successful ways that undermine nan original design.

3. Move From APIs to Business Capabilities

Having a ubiquitous connection is simply a prerequisite for defining business-oriented APIs.

“The companies that person done nan champion person stitched together APIs successful ways that matter to businesses,” Lane said. “The adjacent loop is moving from resources to ‘capabilities’ aliases ‘experiences.’”

Lane defines capabilities arsenic “open source, declarative, standards-based integrations aligned pinch business outcomes wrong circumstantial domains. They supply nan building blocks needed to present and automate integrations crossed countless internal, partner and third-party systems. Capabilities thief rebalance really we deliberation astir and execute integrations crossed nan sprawling ecosystems we dangle on.”

Lane’s ideas astir capabilities are calved from a number of different disciplines but overlap pinch “aggregates,” which “Domain-Driven Design” defines arsenic “a cluster of associated objects that we dainty arsenic a portion for nan intent of information changes.” Good capabilities are business-aligned, quality and machine-readable, composable, declarative, governed, and executable crossed aggregate systems.

Daniel Kocot frames “capability thinking” arsenic “placing accent connected what a level aliases strategy tin really do for its consumers, and really those actions tin beryllium documented, standardized and made reusable crossed usage cases … Capability reasoning reframes nan portion of design. Instead of exposing granular resources, platforms picture discrete business functions specified arsenic Ship Order, Process Payment aliases Approve Loan.”

The word “capabilities” has recovered caller life successful describing what AI agents tin do, but it besides reveals gaps betwixt what enterprises deliberation they tin do versus what their architecture really supports. Agents request to observe what systems are tin of and determine which capabilities to use, based connected goals and context. As Mike Amundsen puts it, autonomous clients request “a paper of possibilities,” not conscionable a database of endpoints.

4. Establish Clear Boundaries for AI

Lane contends that having a map, establishing ubiquitous connection and doing nan domain-driven creation activity intends that your AI activity will beryllium amended scoped. “Your MCP [Model Context Protocol] servers will person nan correct magnitude of devices for a definite group of products, customers aliases statement of business.” Conversely, if you don’t person well-defined boundaries, you summation information vulnerability and risk.

With these things successful place, nan adjacent steps dangle connected business context. Less risk-averse companies are “publishing MCP servers publically and encouraging group to build absorbing things connected them,” Lane said. In much regulated industries, nan attraction will beryllium connected operations and developer platforms, pinch nan extremity of expanding developer velocity.

Start With API Fundamentals for AI Success

Lane’s attack requires enterprises to commencement pinch nan fundamentals: establishing a communal vocabulary, mapping their API scenery and knowing what they’re tin of coming earlier racing toward what AI mightiness alteration tomorrow. As he emphasizes, this activity isn’t conscionable astir method architecture. It’s astir getting engineers, merchandise managers and business stakeholders aligned astir nan aforesaid connection and bounded contexts.

For executives wondering wherever to begin, nan reply is remarkably simple: Start tagging and cataloging. Define nan vocabulary for a circumstantial domain, representation nan services and resources wrong it, and found clear boundaries astir what you’re trying to accomplish.

This foundational activity whitethorn look unglamorous compared to spinning up nan latest AI agent. But this willingness to slow down and deliberation cautiously astir language, creation and business alignment separates nan enterprises whose AI investments will amplify their strengths from those whose investments will simply magnify their dysfunction.

Group Created pinch Sketch.