API pillars serve as the guiding principles that define the foundation and direction of an API platform. They align organizational goals with technical execution, ensuring consistency, efficiency, and strategic focus.

In this article, we will explore the concept of API pillars, their critical role in API platform success, and how to establish a set of pillars tailored to your organization’s unique needs. Whether you are embarking on your API journey or seeking to refine an existing strategy, understanding and implementing these pillars will be instrumental in achieving long-term success.

What are API Pillars?

API pillars are broad statements that outline an organization’s core principles and areas of focus required to operate successfully. Market needs, regulations, security, and operational efficiency often shape API pillars. In some cases, API pillars may be standard across industries, while others are unique differentiators tailored to specific business needs or market demands.

Why do we need API Pillars?

API pillars help teams make smaller decisions quickly and easily. They underpin your standards, practices, and policies that support your overall API platform strategy. Without clearly-defined API pillars, teams will fail to prioritize their work and operate the API platform successfully.

Establishing a Foundation for Your API Pillars

Before we can define our API Pillars, we must recognize that nearly all IT-related pillars fall into three areas: strategy and governance, management, and operations. We extended these areas into the API platform to align with these IT foundational areas to ensure familiarity and consistency in execution across the IT landscape:

1. API Strategy and Governance - Pillars related to the platform strategy, business alignment, governance, and enablement associated with the API platform. Business alignment is a critical aspect of governance and ensures that the API platform is an extension of the business goals and business architecture.

2. API Management - Pillars related to the ownership and management of the overall API platform and individual platform APIs. This includes portfolio management, domain-level ownership of platform APIs, and the API management lifecycle.

3. API Operations - Pillars related to security and operations of the API to ensure that all platform APIs are continually evaluated for proper security measures, optimized deployment, and continuous monitoring and improvement.

The division of policies into these three foundational areas offers a versatile model that applies broadly across IT domains. It is important to note that these areas are widely used in other IT governance domains and are not exclusive to APIs. They serve as foundational pillars in managing and governing various IT systems and services. By aligning to these three common areas, the API platform may be managed similar to other IT policies, systems, and services.

The 8 API Pillars of an API Platform

Through a decade of partnering with organizations to establish, grow, and mature their API strategy and execution, we have identified 8 pillars for any API platform:

API Strategy and Governance

Pillar #1: Strategy & Business Alignment champions the importance of APIs in driving business success and innovation, built upon transparent communication and a clearly communicated vision. When this pillar isn’t applied, organizations lack a focus on the API platform, resulting in fragmented execution driven by projects rather than a platform mindset.

Pillar #2: Governance & Enablement embodies our commitment to upholding rigorous standards and continuous improvement within the API management practices. It also fosters an environment where consistency in API delivery is paired with the flexibility to evolve, enabling the organization to meet both current and future demands efficiently and effectively.

API Management

Pillar #3: Portfolio & Domain Ownership underscores our dedication to effective management and strategic oversight of our digital assets to maximize both operational efficiency and value generation. Collectively, these policies ensure that our digital portfolio is both aligned with our strategic objectives and optimized to support current and future business needs.

Pillar #4: Discovery & Documentation ensures that all internal and external stakeholders, from software engineers to business analysts, can easily access, understand, and effectively leverage APIs to reduce redundancy, foster innovation, and drive efficiencies across the organization.

Pillar #5: Design & Delivery commits to the delivery of robust, scalable, and secure APIs through a disciplined and efficient design and delivery process. It also helps to enable faster time-to-market and greater adaptability to meet the evolving needs of our users and the marketplace, while avoiding the creation of fit-for-purpose APIs that lack reusability..

Pillar #6: Consumer Onboarding & Adoption streamlines the initial engagement and continuous development process for software engineers consuming platform APIs. This pillar ensures a swift and smooth transition from initial contact to active development to encourage long-term satisfaction and success among consumers utilizing our digital assets.

API Operations

Pillar #7: Security & Operations ensures the highest standards of security and operational excellence across our API ecosystem, to maintain the trust and reliability of our customers, partners, and stakeholders.

Pillar #8: Runtime Management & Monitoring applies API ownership through monitoring, continuous improvement, and stakeholder engagement.

Getting Started with your API Platform Pillars

To identify your own pillars for your API platform, it’s important to first identify the fundamental areas required for success, then group them based on their relevance to the organization.

After selecting the key pillars, create brief statements for each to clarify how they underpin the business and guide your API platform’s strategic direction.

Finally, feel free to leverage the pillars outlined above as a starting point. These pillars represent over a decade of API strategy development for global organizations. However, keep in mind that you may need to make adjustments based on any industry-specifics that may impact your API pillars.

Without a clear and firm foundation established, day-to-day decisions will slowly erode your API platform effectiveness.

Eager to get started? Contact us to jumpstart your API platform effort.

This article will explore the challenges of today’s IT-centric API platforms and outline the mindset shift required for transitioning to a business architecture-driven API platform. By grounding your APIs in business capabilities and aligning them with the needs of your stakeholders, you can create a cohesive, scalable, and impactful API ecosystem that drives real business value.

What is an API Platform?

What exactly is an API platform? It’s a term often misunderstood or overused, applied to everything from technical systems to business strategies. While the concept originated as a business model, it has evolved into digital platforms that serve diverse stakeholders, sometimes focusing solely on one party.

An API platform is an ecosystem of thoughtfully designed APIs that empower your workforce, partners, and customers to achieve meaningful outcomes.

Let’s break this definition down. First, an API platform is an ecosystem — not just a collection of individual APIs but a cohesive, interconnected system. These APIs are intentionally designed for seamless interaction and interoperability, enabling smoother workflows and integration across the board. Grouping a few APIs might be a good starting point, but it’s not the ultimate goal.

The ultimate goal of an API platform is to empower every stakeholder. It equips your workforce with tools to innovate and improve efficiency, provides your partners with seamless integration opportunities to foster collaboration and growth, and delights your customers with consistent, personalized experiences that build trust and satisfaction.

Achieving this requires intentional design and strategic alignment. Each API must address business and user needs while driving measurable outcomes. When executed effectively, an API platform creates new opportunities for innovation, fuels value creation, and serves as the foundation of your organization’s digital evolution.

Where Today’s API Platforms Fall Short

Many enterprise API platforms today are rooted in existing systems. These systems often carry catchy names like Ares and Genius, or acronyms like RMS and SMART. APIs are typically developed to wrap these systems, providing data access for reporting or basic transactional support. While this approach may seem practical, it often leads to significant challenges.

As these APIs proliferate, they begin to “leak” internal system details. This makes them fragile, as changes to the underlying systems can ripple through and disrupt the APIs. More critically, these APIs fail to deliver value to external partners, who are not interested in the specifics of enterprise systems. Partners care about access to data and transactional capabilities, not your internal architecture.

API Platforms Must Empower Your Partners and Customers

Shifting to an API platform mindset requires a fundamental change in perspective. Rather than focusing on the systems themselves, enterprises must start by examining the journeys of their partners and customers through their business capabilities. Mapping platform APIs to these user journeys ensures the APIs are relevant to a broader audience and aligned with real-world needs.

In this new mindset:

• APIs reflect user needs, not internal structures. They adopt the vocabulary of partners and customers, moving away from internal acronyms and shortcuts.
• APIs empower outcomes. By focusing on delivering thoughtful APIs, enterprises can provide tools that support the end-to-end experiences of their users, rather than just exposing data from internal systems.
• APIs support both external and internal goals. While user-facing APIs drive partner and customer success, internal APIs streamline workflows and reinforce the operating model.

By embracing this API platform mindset, enterprises can produce cohesive, intentional APIs that empower stakeholders and deliver meaningful outcomes. This shift represents a departure from the fragmented, system-centric approach prevalent in many organizations today. Instead of simply delivering APIs, enterprises create a robust ecosystem designed to scale, adapt, and thrive in an ever-evolving digital landscape.

Successful API Platforms Start with Business Architecture

A successful enterprise API platform is more than a collection of APIs; it is a strategic enabler of business outcomes. To achieve this, organizations must integrate business architecture into their API platform efforts. Business architecture serves as a structured framework for aligning an organization’s strategic objectives with its operations, capabilities, and processes. By providing a holistic view of the business, it ensures that APIs are designed to meet real-world needs rather than just exposing data or systems.

To build a cohesive API platform that supports the business, organizations must incorporate business architecture into the design of every API. This process begins with identifying and mapping business capabilities to APIs. Business capabilities define the core functions an organization provides to deliver value. They describe what the business does, independent of how it is done.

By grounding API design in business capabilities, APIs become tools for executing strategic priorities, not just technical endpoints.

Platform Capabilities: The Digital Layer of Business Architecture

Platform capabilities bridge business architecture and APIs, turning desired outcomes into reality through automation. These capabilities are often implemented as APIs but may also include data products, events, or message streams. They empower stakeholders by providing the means to interact digitally with the organization.

Each API added to the platform must be intentionally crafted as a platform capability that reflects and supports the organization’s business architecture. This ensures:

• APIs represent business capabilities, making them relevant and valuable to stakeholders.
• APIs are aligned with user journeys, supporting seamless interactions for customers, partners, and employees.
• APIs contribute to broader organizational goals, enabling innovation and measurable outcomes.

Final Thoughts

Shifting to an API platform mindset is not just a technical transformation—it’s a strategic imperative for enterprises looking to thrive in a rapidly evolving digital world. By focusing on user journeys, aligning APIs with business capabilities, and leveraging business architecture as a foundation, organizations can create APIs that are more than endpoints—they become enablers of business success.

An API platform rooted in business architecture ensures that every API contributes to measurable outcomes, supports stakeholders’ needs, and scales to meet future challenges. This approach fosters innovation, improves usability, and positions the enterprise as a leader in delivering value through digital ecosystems. By embracing this mindset, your organization can transform its API strategy into a powerful engine for growth and competitive advantage.

• An API platform requires cross-functional cooperation, not just a focus on API design and delivery. Engineering practices, cloud native practices, product engineering practices, and data management practices all contribute to make your API platform work effectively.
• Many enterprises push their internal services out to partners, but this only serves to frustrate them. Services are for internal composition, not external consumption. Partners don’t want API “LEGO bricks”, they want to experience value delivered through outcomes and inquire about the status of workflows. This requires a different approach to API design than internal decomposition through services.
• It takes more than capable engineers for a successful API platform. Be sure to involve product leaders to make your API platform more effective and that can apply product ownership to their subset of the overall API portfolio.
• Dedicated roles in API governance are the only way to make it happen. A “side of desk” approach is rarely effective in delivering long-term impact, even if it appears to be effective in the short term.
• Establish a clear API platform strategy, then communicate it early and often. Everyone in the enterprise should have a clear understanding of how APIs are involved in daily operations.
• Be sure to define your API platform pillars and policies, then build standards and processes to support them. Without a clear and firm foundation established, day-to-day decisions will slowly erode your API platform effectiveness.
• Obtain executive buy-in and budget, even if it is a smaller budget to start. If you lack executive CIO buy-in, you will always starve for budget and people, and it will always be deprioritized for other urgent items. Enterprises that start bottom-up will always have their initiatives replaced by higher-priority deliverables.
• Industry standards are nice for external interoperability and data portability, but they almost always lack sufficient guidelines for an effective API platform. Embrace, extend, and be prepared to design and deliver your own APIs when needed.
• API platforms are most effective when they align with your business architecture and strategy. This means that enterprises must make an effort to understand and blend their operating model with their APIs.
• Align the enterprise API platform with business objectives through your API strategy, pillars, and standards. Without it, your platform will be less effective as teams lack focus, often going in many directions at once.
• Invest in your API documentation efforts. Get better at producing thoughtful, comprehensive API docs. API documentation reduces frustration, support costs, and can create an barrier to customer/partner churn.

Here are some additional insights for the design and delivery of APIs:

• If using API design first, the delivery effort is reduced and can be optimized as needed through decomposition of the desired API capabilities. Code-first API delivery is useful when there are technical risks that must be identified and mitigations identified. Start code-first, identify risks, then go back to design-first to take an outside-in approach to the API itself.
• Specifications such as OpenAPI, AsyncAPI, JSON Schema, and others must be verified against the implementation or API drift will emerge before the first version is delivered to production.
• Not all developers/engineers have the same experience, so expect to spend time training your staff. Anecdotal evidence is between 25%-90% of your engineers have never seen HTTP over the wire. These are the same folks often assigned to design an API, which results in poor understanding and reinventing the HTTP wheel. This is why we developed API training courses very early on, as the numbers were often higher than today’s average of 25%.
• Federated API coach programs allow enterprises to scale your efforts, especially when resources are limited. You must roll out API design coach training and certifications early to ensure your enterprise is able to spread the experience across teams while you work to upskill teams.
• System analysis and design are the most critical skills for managing an API platform and portfolio. These skills haven’t been taught as much in recent decades, which is the root cause of many failing API platforms.

Anything I missed? Drop me a note or tag me on LinkedIn or X/Twitter.

While terms like “guidelines” or “guardrails” may sound like a light touch approach to managing APIs, they often result in optional practices rather than consistent ones. When guidelines are implemented properly, they offer more generalized considerations that offer flexibility where standards do not exist. However, relying purely on guidelines leads to a lack of cohesion across teams, missed automation opportunities, and even riskier outcomes when policies are loosely interpreted or inconsistently followed. Governance, by contrast, offers a structured framework that helps organizations ensure APIs are built, managed, and monitored in alignment with enterprise-wide policies and standards.

This article dives into why governance is a non-negotiable element for API programs and how it benefits organizations in the long run. Let’s unpack the components of governance, how it differs from guidelines, and why it plays an integral role in building robust, scalable API ecosystems.

Why API Governance Is Often Misunderstood

The word “governance” often conjures up images of restrictive processes, extra layers of bureaucracy, and potentially reduced agility. As a result, some teams actively avoid using it, opting instead for softer terminology like “guidelines” or “guardrails.” While these terms may sound more flexible, they often lead to inconsistency and can actually increase inefficiencies as teams develop divergent approaches.

The hesitation around governance often stems from historical practices in large organizations, where compliance and governance have sometimes become overly burdensome, adding unnecessary delays to projects. But API governance, when done right, is not about policing or stifling creativity — it’s about creating a sustainable structure that supports and scales API initiatives across the enterprise. Governance enables teams to better align with business objectives, set clear expectations for delivering production-ready APIs, and is often automated where possible.

API Governance is Non-Negotiable

So what’s the difference between “guidelines” and “governance”? Guidelines are typically informal, offering teams advice or best practices they may choose to follow. Governance, on the other hand, establishes non-optional standards and practices, often driven by overarching enterprise policies. Where guidelines leave room for interpretation, governance sets definitive expectations, ensuring consistency across the board. This is particularly critical in enterprise settings where multiple teams may be working on API initiatives, each with its own approach and potentially conflicting priorities.

Consider this analogy: guidelines are like lane markers on a highway, suggesting where to stay but allowing drivers to cross over when it is legal and safe to do so. Governance, in contrast, is the set of road laws—unbreakable rules enforced for safety, efficiency, and predictability. In the API world, governance translates into well-defined standards for versioning, security, documentation, and performance monitoring, creating a reliable, predictable API ecosystem that’s easier to maintain and scale.

Opting for “guidelines” over governance might feel easier in the short term, but this decision almost always leads to long-term challenges. Without governance, inconsistencies pile up, technical debt grows, and the lack of structure can result in costly rework. Additionally, as APIs become a key part of customer-facing applications and services, poor governance can lead to a lackluster customer experience and reduced trust in the organization’s digital products.

A Fintech Example of Guidelines Over Governance

When guidelines disguised as standards exist, they can be overridden easily to meet a deadline or skip a step in the go-live process. This happened to a fintech company sometime in 2018. During an audit, they discovered that they had over a dozen APIs exposed without any kind of authorization being enforced.

How were over a dozen APIs exposed publicly, without any sort of authorization? The issue started with a VP-level override. Time was short and the API was seen as the blocker for delivery. After being denied an exception by the API Center of Excellence (COE) that was responsible for enforcing the guidelines, the VP was called in to escalate the issue. Eventually, another VP with proper authority was called into a meeting with the team and their VP. Since a formal policy didn’t exist, it was seen as a “nice to have” rather than a critical element of API security. Without a formal policy, the VP allowed the exception to override the COE’s guidelines and allow the API to be deployed without any kind of security controls.

Once the issue was identified through an audit, the APIs were flagged and an investigation was started. Thankfully, a thorough discovery process yielded no indication of any compromises. They were able to quickly bring them in line with proper security practices without incident. That may not always be the case, however.

After this fintech incident, a new enterprise-wide policy was created to require all APIs to be protected by an API gateway with proper authorization settings. CI/CD processes were updated and change management was implemented to bring all teams, managers, and skip-level managers in alignment with the new policy. What was a guideline was upgraded to an enforced policy by the fintech company moving forward.

The Benefits of API Governance

The fintech example, above, is only a single example of what can happen if you choose to implement guidelines rather than formal API governance. So, what are the benefits of an enterprise taking a serious look at implementing API governance? There are five that I identify as foundational to any API program or platform:

1. Alignment with Business Objectives An API governance framework helps ensure that all APIs are built in alignment with the organization’s overarching business goals. This may include requirements around interoperability, scalability, or specific customer needs. Without governance, individual teams might prioritize local objectives over organizational ones, leading to fragmentation. With governance, however, API initiatives can be directed toward unified goals, ensuring that APIs don’t just serve the needs of a specific team but contribute to the enterprise’s strategic vision.

2. Consistency and Predictability With a governance framework in place, every API within the organization adheres to a common set of standards and practices. This consistency not only helps developers by providing clarity on what’s expected but also benefits end users, who can expect uniform performance and behavior across the APIs they consume. Predictability in how APIs operate, how they’re documented, and how they’re versioned is essential for seamless integration and use across platforms.

3. Enhanced Security and Compliance In the absence of API governance, each team might handle security differently. This piecemeal approach can expose the organization to significant risks. Governance ensures that security protocols—such as encryption standards, authentication requirements, and data protection policies—are uniformly enforced across all APIs. By integrating security measures into the governance framework, organizations can minimize the risk of breaches and ensure compliance with regulatory standards.

4. Greater Automation and Efficiency Governance enables automation. When standards and processes are clearly defined, they can be automated to enforce consistency without manual intervention. Automated checks can validate that new APIs comply with naming conventions, security requirements, and versioning rules before they go live. This streamlines the development pipeline and reduces the burden on development teams, allowing them to focus on building high-value features rather than handling repetitive tasks or chasing down errors due to inconsistent practices.

5. Improved Developer Experience and Collaboration When governance is in place, developers have a structured, predictable framework to follow, making it easier for them to build and deploy APIs effectively. They don’t have to wonder what versioning scheme to use or guess at security protocols; everything is clearly defined within the governance framework. This boosts productivity and enhances collaboration between teams, as everyone operates within the same system of expectations.

Final Thoughts

API governance isn’t about restricting developers or burdening teams with extra processes; it’s about creating a clear, sustainable path for the organization to achieve consistent, secure, and efficient API management. For organizations serious about leveraging APIs as strategic assets, governance isn’t just helpful—it’s essential.

By enforcing clear standards, leveraging automation, and aligning with enterprise-wide policies, governance ensures that APIs can be developed, deployed, and scaled sustainably. It might require an upfront investment of time and resources, but in the long term, governance pays off by reducing risk, improving efficiency, and enabling consistent, predictable outcomes across the organization’s API ecosystem.

In this final article of the series, I’m going to explore how Blackbird enables teams to collaborate by exploring their features from a multi-team perspective. We will explore API discovery, adding a new API, exploring the API in the Blackbird web interface, and the options available to interact with the API from the command line and code.

Discovering Existing APIs

One of the challenging steps for a growing API practice is to manage their catalog of APIs. While some tools exist, they are often out-of-band of the developer workflow. With Blackbird , they provide a searchable catalog to locate a previously registered API.

Let’s imagine that I’m looking for a TODO List API. All I need to do is click on the ‘APIs’ feature, then search for a keyword, such as ‘TODO’:

In this example, the API already exists. As a developer, I can immediately start to look at the operations provided and explore the API from within the web interface. This helps to drive a consume-first culture, avoiding the need to build duplicate APIs by first searching for existing ones in the API catalog.

What happens if I don’t find the API I need? Then I probably need to create one of my own. I explored this flow as well.

Adding Your API to the Catalog

Since the first article focused more on the Align-Define-Design-Refine (ADDR) API design first process, let’s walk through the process of registering a new API with Blackbird based upon an existing OpenAPI Specification.

The first step is to upload the OpenAPI document:

After the document is parsed by Blackbird, it displays the details it discovered and allows me to make any adjustments necessary:

Once I click ‘Create API’, the API is added to the Blackbird catalog and available for exploration. I liked that it recognized the tags I assigned to the operations, and the option to immediately create a mock instance of the API. This supports my recommended flow of design, gain rapid feedback to refine your API design, and update the design prior to delivery.

Exploring the API

After the API is registered in the catalog, I am presented with an API details page in Blackbird. The page lists the servers and owner details from the OpenAPI document. Nice touch. While the owner email isn’t linked on the page, I like the idea that this was captured as I might be able to browse the catalog by API owner in the future by simply clicking the owner’s email.

Along with basic details, the list of endpoints (sometimes called API operations) are provided. The tags assigned to each operation are included, along with the summary. A ‘Preview’ button takes us to the details of the operation, where we will get to interact with our API:

Interacting with the API

Blackbird offers additional details about the API, including example requests and responses. This is similar to most API documentation tools. Since we chose to generate a mock instance when we registered the API, we can provide request details in the provided form and press the ‘Send API Request’ to see the response from the live mock instance:

Not only can you interact with the mock instance from this page, Blackbird also provides a cURL command that we can copy and paste into a shell:

If the owner of the API has deployed a running instance of the code to Blackbird, the API consumer can also work directly with the deployed instance instead of a mock. This supports the typical collaboration workflow between development teams, from discovery to viewing documentation and then interacting with the API to see how it works.

Wrapping Up

Blackbird proves to be a powerful tool for API teams, offering seamless collaboration from discovery to integration. Its API development workflow—from cataloging existing APIs to generating mock instances for testing—makes it easier for teams to avoid duplication and focus on consuming and enhancing APIs. Whether developers prefer a web interface or direct command-line interaction, Blackbird offers an efficient, consume-first culture across development teams. In addition, it encourages a design-first approach that keeps developers in a single workflow without the need to switch between various tools. I look forward to exploring Blackbird further as the product continues to evolve as they approach their general availability estimated date of October 1.

While ADDR helps teams to deliver an API design that is ready for delivery, that doesn’t mean that we are done. We still need to code the API implementation, integrate it with other developers, and debug the API when we encounter problems.

In this article, I’ll share my findings of how Blackbird supports generating boilerplate API code (in GoLang) and also enables remote development, debugging, and integration. This will extend the ADDR process into the delivery phase of the API lifecycle.

Moving from Mocks to API Implementation

One of the challenges I see teams encounter when transitioning from API design to delivery is the need to shift between a variety of tools. While there are existing code generators that exist to help automate the creation of boilerplate code, developers must spend time finding a code generator and then figuring out how to install it locally as part of their tool chain. This can slow down the flow of development.

Blackbird offers a built-in code generator with initial support for the Go Programming Language from their command line tool (CLI). The code generator is open source and can be used as a foundation to support generating APIs using your own favorite patterns and practices in Go, or used as a template for your own favorite language and framework.

Since we generated the OpenAPI document using the Blackbird AI feature, our OpenAPI document isn’t on our local laptop. All we have to do is download the generated OpenAPI document from Blackbird to start generating code from the CLI. I did this from their web interface already, but if you are following along then you will need to ensure you have your document stored locally.

To get started with the Blackbird generator, I verified that I had Docker installed locally. Then, I installed their CLI and then used their usage guide to help me run the generator:

blackbird code generate -s ADDR-bookstore-api.json -t go -o bookstore-api

To generate the boilerplate API code, the CLI asks a few specific questions. The usage guide helped me to understand how best to answer these questions. Below is a screenshot showing how the full process worked:

The generated code is modular, with a clean separation between the schema objects that represent our resources and the supporting code to handle each operation. By default, the code returns a 501 Not Implemented response as a placeholder.

Now that we have generated a boilerplate API implementation within Blackbird, let’s run it locally.

Running the Generated Code Locally

Now, it is time to launch our generated code locally to see it running. We will cd into the folder that was generated and use the standard go run command to start:

go run cmd/bookstore-api/main.go

Here is what we will see:

I then pointed my browser to http://localhost/books to see that it was working:

We can check the output logs from our local running instances to see that it reached our generated code successfully:

Great! Everything is working fine so far. At this point, we can start adding implementation details. As we do this, we will want to make our API remotely accessible for others to use. Let’s do this next using Blackbird’s relay service.

Running the Generated API Code Remotely

As the generated code is replaced with working code, you may want to obtain feedback on how the API is behaving. Typically this would require installing yet-another-tool to relay the local API responses to another developer. Blackbird offers this as part of their solution, keeping us from installing a separate tool.

Using the usage guide, I was able to use the Blackbird CLI tool to build it using Docker, register the API with Blackbird, and obtain a URL to try out the API from anywhere:

blackbird code run addr-bookstore-api --dockerfile Dockerfile --context . --local-port 80

You will see the full process, from build to packaging into a container, and registering the API on your console. When it has completed the process, it will provide the URL and let you know it is running locally, ready to accept inbound requests:

I then composed a URL using the base URL provided, appending /books to the end to verify that everything is working correctly:

For team members that want to use the mock, they can login to Blackbird and click on the Code screen from the left navigation bar to find the URL:

Nice! I can now continue with the typical development work, then make it available for feedback and early integration as needed. However, this feature only works if our laptop is online. So, let’s now explore deploying our API to Blackbird’s dedicated environment.

Deploying our API to a Dedicated Environment

The last thing that we want to explore is deploying our API to a dedicated Blackbird environment. This will allow team members and API consumers to access the API using a unique URL. Unlike the remote access we just explored, this approach doesn’t require a developer laptop to be running to access the API. Instead, Blackbird hosts a containerized instance of your API for easy access at any time during the API development lifecycle.

blackbird deployment create addr-bookstore-api --dockerfile Dockerfile --context .

Wrap-up

To recap our progress so far, we:

1. Turned our ADDR-based artifacts into an OpenAPI Specification with the help of Blackbird’s API bot (see previous article)
2. Produced a mock implementation based on the OpenAPI document so that we can explore the API before we start writing code (see previous article)
3. Generated an API implementation in Go using the Blackbird code generator
4. Implemented each API operation by running locally, then using Blackbird’s relay capabilities to make them available for our team and API consumers for quick testing and feedback
5. Deployed our API to Blackbird for developer availability of our API implementation

We did this all in one tool, without the need to copy-and-paste or write automation scripts to manage our API development lifecycle.

I’m looking forward to seeing what generators the community and the Blackbird team produce in the future. Starting with Go was a good idea, though I would expect Spring Boot, Node.js, and other frameworks to be supported, as these are commonly encountered in enterprises today.

In this article, I’ll provide a brief review of the ADDR process, then use the artifacts from ADDR to help me design and mock the API. I’ll capture some tips and call out a few wishlist items that I hope Blackbird will incorporate into future releases.

Understanding the ADDR Process

The ADDR process is a methodology to guide organizations through the complexities of API design and implementation. It comprises four key phases:

1. Align: Establishing the strategic purpose of the API.
2. Define: Detailing the API’s capabilities.
3. Design: Creating the API’s structure and user experience.
4. Refine: Iterating based on feedback and testing.

Focusing on the Align and Define stages can significantly influence the success and efficiency of the API design process.

An example ADDR process

Improving the API design begins with crafting job stories to better align on the problem, job-to-be-done, and desired outcome(s):

Next, we expand the job stories into activity steps to better understand the work involved:

Finally, these insights are modeled as an API profile and associated resources:

The API is now ready to be designed using the best-fit API design style, such as REST, GraphQL, or gRPC. Let’s see how Blackbird, a new product offering from Ambassador, can further accelerate the API development process.

Using Blackbird with ADDR to accelerate API design

For those not familiar, Blackbird helps you accelerate your API development lifecycle by reducing the margin for errors, improving consistency and reusability, decreasing time-to-market, and driving positive business outcomes. It can work with an existing OpenAPI Specification document, or you can use their built-in AI bot to describe your API and let it generate the OpenAPI document automatically.

Generating an OpenAPI Specification using GenAI

Let’s try using our insights from ADDR to generate an OpenAPI specification. The first thing we need to do is craft a prompt using our existing ADDR artifacts. Here is the prompt I composed:

This generated an OpenAPI Specification that reflected the previous work completed using the ADDR process:

While I would typically use multiple paragraphs or upload a complete specification, Blackbird’s AI bot only accepts a single paragraph currently. Hopefully, this will improve over time by offering a more robust set of options for prompt input.

Reviewing the API Design

Now that the API has been generated, it is automatically imported into my catalog of APIs. I can then review the API operations generated:

I then downloaded the OpenAPI specification and reviewed what it generated to make sure it has everything I want in my specification. Here is a screenshot of the generated OpenAPI Specification, with details collapsed:

Looks good so far! We have the right operations and even have our success and error responses. Plus, it generated schema components for reuse, so no need to do that ourselves. This saves hours of typing and troubleshooting and also avoids moving between a variety of tools, downloading and uploading artifacts along the way.

Refining your API design with mocks

The next step in ADDR is to refine the API using a mock of our design. This ensures our design includes everything our API consumers will need. Typically, I would jump to yet another tool to create a mock. With Blackbird, this is built in with a single click:

I’m then taken to the mocks section, where my mock implementation is created, launched, and ready. I now have a URL endpoint that I can use to make mock requests:

Using the mock URL endpoint provided, I appended /books to the URL and was able to send a GET request to my mock server and receive a response:

This mock helps me to see if I’m missing any resource properties and will go far to accelerate the API consumer’s work while the implementation is built out. In an upcoming release, Blackbird will offer customized mock responses. For now, crafting your own OpenAPI Specification with example values is the best way to get real-world data into the mocks.

Conclusion

I’ve been instructing individuals and teams on using the ADDR API design process for almost a decade. In that time, the process has helped teams to accelerate their API design and delivery lifecycle. The challenge has been finding a tool that can help take ADDR artifacts and drive API delivery.

With the addition of Blackbird, I can now accelerate the API design lifecycle by importing an existing OpenAPI document, using GenAI to produce an OpenAPI document, and see my API in action by generating and deploying a mock API with a single click. While it can do more than just help develop APIs, I’ll leave that for a future follow-up as I continue to dive into Blackbird to see how it can accelerate other areas of the API lifecycle.

This article is part of APIFutures, a distributed, creator-led effort to identify the most significant opportunity and/or the greatest challenge facing the API community in 2024. You can check out other articles and viewpoints on the APIFutures landing page.

For some, 2023 was an amazing year for their API program. For others, 2023 will be remembered as a year where API programs were met with challenges such as reduced budgets and a mandate of “do more with less”. No matter what last year was for you, I want to share some insights of where I believe some of the biggest opportunities are for API programs in 2024.

Opportunity #1: A Leaner API Program

Digital transformation initiatives have been underway for 5 years or more now, with the earliest adopters having started the effort 8 years ago or longer. Millions have been poured into the initiatives to realize cloud migrations, the shift to platform engineering through technologies such as Kubernetes, and a focus on API first culture.

Last year, the budgets slowed down, forcing the “do more with less” approach to API programs and enterprise IT in general. Some enterprises saw a reduction in their API program budget, while others continued to maintain their commitment to their API program and an API first culture.

Things are shifting back to the business. No more expansive rewrites and modernization. We had years to get that done. Time to deliver value to business and customers. APIs are at the center of this, but it will require a leaner API program.

This shift to a leaner API program was seen through several trends that we predict will continue into 2024:

• Self-service API training resources to equip their product owners and technical leadership in necessary API skills
• Establishing a federated API coach program to equip leaders across the organization
• Adding API governance engagement models to extend the effectiveness of the API program through office hours, collaborative design sessions, and API design facilitation for high-profile initiatives

Summary: Expect a continued effort to produce a leaner API program through self-service API training, establishing a federated API coach program, and new API governance engagement models that make better use of time and resources.

Opportunity #2: Realizing the Goal of API Reuse

When we speak with organizations of all sizes and industries, one of the top 3 goals for their API program is reuse. Whether the reuse is focused internally (“localized API reuse”) or intended to drive optimized partner and customer integrations (“globalized API reuse”), the intent is the same: organizations are seeking a culture of “consume when possible, build when necessary”.

Last year, we saw organizations focusing their efforts around API portfolio ownership, which included disciplines such as API discovery, API cataloging, and API lifecycle management. Some organizations used these efforts to track unused APIs (“zombie APIs”) or unknown APIs (“shadow APIs”) to prevent them from compromising their systems. However, the longer-term goal by most of these organizations is to catalog and offer APIs to their internal developers, partners, and customers.

Summary: Expect to see a continued focus on API portfolio ownership, including the discovery and cataloging of all types of APIs and digital assets.

Opportunity #3: The Growth of the API Product Manager

APIs are becoming the lingua franca of today’s digital business. APIs are the digital front door to every organization. This is resulting in conversations about API capabilities and API onboarding by everyone - from account managers to product leaders and executives.

Last year, we saw that many organizations had to quickly upskill their staff in API fundamentals. We also noticed that organizations had to adjust their processes to support routing API-related discussions to product owners or business product managers that were familiar with the APIs in the particular domain area.

No longer are product owners and product managers limited to overseeing partner integrations, web apps, and mobile apps. Digital assets such as APIs, events, and data will become the responsibility of product leaders to own and manage. Training in the concepts of applying a digital product mindset and understanding of API fundamentals will be necessary for this new role.

Product leaders will also be expected to manage APIs through their full lifecycle. This means applying a digital product mindset, including product discovery, to APIs. Product leaders will rethink the fit-for-purpose approach to API delivery, instead applying productization for reuse into the typical partner integration project.

This will require the specialized role of API product manager to become more common in organizations starting in 2024. This role will demonstrate the use of APIs for their partners by making simple API requests to demonstrate value. They will be participating in API onboarding calls that were traditionally left to technical leaders to help them identify gaps in the onboarding process, spot improvement opportunities in API documentation, and add missing API capabilities to their backlog. Existing product leaders will require coaching in skills such as API fundamentals, API design, and full API lifecycle ownership.

Summary: Expect to see an increased focus in the role of API product manager, with a focuse on the full API lifecycle, skills in using and designing APIs, and API productization to better support new business opportunities.

Final Thoughts on the Evolution of API Programs

The landscape of API programs and governance is poised for significant evolution in 2024. Organizations are moving towards a more efficient and effective management of their API initiatives, driven by the need to optimize resources and deliver value more rapidly. Three key opportunities stand out:

1. The Development of a Leaner API Program: Enterprises will streamline their API programs, focus on self-service API training, implement federated API coaches, and expand their API engagement model. This lean approach aims to enhance effectiveness while optimizing the use of resources.

2. Enhancing API Reuse: The growing emphasis on reuse will drive demand for API portfolio ownership, focus on API discovery and cataloging, and improved lifecycle management of APIs. This approach seeks to maximize the reuse of APIs, both internally and externally, aligning with the principle of “consume when possible, build when necessary.”

3. Rise of the API Product Manager Role: As APIs have become integral to digital business, the role of the API product manager is gaining prominence. This specialized product leadership role will be pivotal in managing APIs throughout their lifecycle while applying a digital product mindset to ensure APIs are fit for purpose and contribute to new business opportunities.

Overall, 2024 appears to be a year where the alignment of API strategies with business goals will be crucial.

User-Driven API Design vs. Data-Driven API Design

User-driven API design, as the name suggests, places the end-user at the center of the design process. The primary goal is to create APIs that cater to the specific needs, preferences, and expectations of those who will consume them. These users could be developers, partners, or even customers.

In contrast, data-driven API design prioritizes the organization and accessibility of data and functionality within an application or system. The primary objective is to expose data and processes efficiently, making it accessible for various use cases.

Historically, a data-driven API design was solely focused on exposing a database table or view as an API. This led to exposing internal data model details to API consumers, an anti-pattern that often results in fragile APIs that can break consumers when the underlying data model changes. All data was treated the same and had the same authorization rules applied.

Due to these inefficiencies, data-driven API design was only considered for specific circumstances. However, API generation software is causing IT teams to give data-driven API design a second look.

Rethinking Data-Driven API Design

With the introduction of API generation software, many of the challenges encountered with data-driven API design are addressed. This new category of API tooling now supports more robust mapping of data to the API resource model, often through a visual builder. Access roles can also be applied to restrict access to the underlying data, ensuring that modifications to the data cannot be made without prior authorization.

Additional patterns, such as pagination and rate limiting, ensure that the API doesn’t negatively impact the underlying data store performance due to large queries or aggressive API clients. Plus, low-code support in many of the tool offerings allows for a more customizable API to meet business needs, without the need to craft each line of code using a traditional approach.

Incorporating API Generation into the API Delivery Lifecycle

This maturity of API generation software tools has IT groups rethinking how they deliver APIs that are meant to support system integration and rapid delivery of data via APIs. Plus, these tools support organizations with a mature API delivery lifecycle to properly incorporate API generation into their common practices. API generation no longer lives outside of the API delivery lifecycle, but rather complements it by accelerating many of its phase.

Below is a summary of how the API delivery lifecycle is accelerated by API generation tools:

Let’s look at each phase and explore how API generation tools can be incorporated to accelerate the API delivery process:

1. Plan: Identifying the Need for Speed and Efficiency

In the planning phase, organizations identify the need for a new API or the improvement of an existing one. This involves defining the API’s purpose, target audience, and strategic goals, as well as outlining the scope and requirements.

Organizations now have the option of taking a user-driven API design approach that is focused on user experience for more complex solutions, while accelerating the design and delivery phases using API generation tools. While some compromises in the API design will be made for the sake of speed, a data-driven API design doesn’t have to directly expose the data model. Instead, customizations and low-code tooling may be used to incorporate both data and user-driven design elements at a much higher velocity than traditional design methodologies.

2. Design: Mapping the Data to the API

During the design phase, the API’s architecture, endpoints, data models, and user interfaces are carefully planned and documented. It is crucial to create a clear design that aligns with the intended use cases and business objectives.

API generation tools shine by offering low-code interfaces that simplify the design of the API. These tools enable designers to visualize and document the API’s structure efficiently, ensuring that the design aligns with both technical and business objectives.

3. Prototype: Visualizing with Agility

Prototyping, a stage critical for validation, benefits immensely from API generation software. By quickly creating functional mock-ups, stakeholders can provide immediate feedback, leading to a more refined and targeted API design. This rapid prototyping not only saves time but also increases the prototype’s accuracy in meeting user needs. Plus, live data from production or sanitized data sources may be used to better understand the API’s design rather than using a test data set.

4. Implement: Streamlined Development

In the implementation phase, developers write the code to build the API based on the design specifications. This phase includes coding, database integration, and the development of any necessary logic.

API generation tools automate the coding and integration tasks, turning weeks of development time into an almost immediate delivery process. This automation reduces human error and accelerates the development process, allowing developers to focus on more complex and creative aspects of API development.

5. Secure: Built-in Security Measures

Security is a critical aspect of API development. In this phase, security measures such as authentication, authorization, encryption, and access controls are identified and implemented to protect the API and its data. In most cases, this involves defining configuration rules that will be applied when publishing to an API gateway.

API generation software provides a low-code method of defining role-based access controls (RBAC), ensuring that security is integrated into the API from the outset. This is a significant improvement from simple code generators that apply no authorization rules without significant effort.

6. Publish and Test: Efficiency in Deployment and Testing

The next step in the API lifecycle is to publish details of the API to an internal API catalog and/or an external developer portal. This makes the API available for use by developers before being rolled out to production to gain feedback from consumers. The phases are repeated to incorporate changes until the API is ready for promotion to a production environment.

Upon publishing, the API enters a crucial testing phase. Here, API generation tools can facilitate automated testing procedures, ensuring comprehensive coverage of functional, load, and security testing. This leads to a more robust and reliable API.

Note that as of this article’s publication date, most API generation tools are not capable of publishing to an API catalog or portal directly. They do generate documentation to assist in this process.

7. Document: Auto-Generated Documentation

API documentation is crucial for users to understand how to interact with the API effectively. This phase involves creating comprehensive documentation that includes usage instructions, endpoints, parameters, and examples. For external-facing APIs, additional documentation may be produced, such as a getting started guide, examples, and an optional reference application.

Documentation is streamlined with API generation software. It automatically generates reference documentation, often in the OpenAPI Specification format. This reduces manual documentation effort and ensures accuracy and consistency.

8. Deploy, Monitor, and Monetize: Continuous Improvement and Revenue Generation

Deployment involves making the API accessible to users and systems in a production environment. It includes setting up servers, configuring network settings, and ensuring scalability and reliability. This step also includes making the API accessible through an API gateway and applying all security configurations. Continuous monitoring is then applied to track API performance, usage, and health in real-time.

API generation software offer rapid deployment and rate limiting to support quick deployment without the need for existing API management infrastructure. Deployments often occur in only a few seconds, without the need to stand up a full CI/CD pipeline.

However, it is not necessary to leverage the capabilities of these tools. Organizations are able to leverage their existing investments in their CI/CD processes and API management infrastructure to properly deploy, secure, monitor, and monetize their APIs.

For organizations looking to generate revenue from the API, the monetization phase involves implementing billing, pricing, and subscription models. It may also include enforcing usage limits and tracking API consumption. API generation tooling typically doesn’t have this built-in, so an API management platform is often required to support monetization.

9. Maintain: Adapting to Change

The maintenance phase is ongoing and involves regular updates, bug fixes, security patches, and feature enhancements. Maintaining API quality and performance is critical to meet evolving user needs. This often involves going through the same lifecycle once again, applying these enhancements into a new API revision.

In the maintenance phase, API generation software simplifies updates and adaptations, enabling APIs to evolve with changing business needs and technology landscapes. Caution must be applied, however, to prevent introducing breaking changes in the API design that could result in API consumers scrambling to adapt to changes. Some tools are capable of warning of breaking changes to prevent causing an outage with API consumers.

Conclusion

API generation software is forcing IT to rethink its approach to API design from user-centric to a hybrid approach that includes data-centric API design. By blending both approaches, enterprises are able to rethink the way they approach their API strategy to support high-velocity delivery. Integrating API generation software accelerates each phase of the lifecycle, from planning to maintenance, API generation software aligns API development closely with business strategies, paving the way for innovation and growth in the digital world.

While API generation software is not a silver bullet, thoughtful application of these tools will enable enterprises to accelerate their integration efforts through a low-code approach to API design and delivery. Unlike tools that promised similar outcomes in the past, these data-driven APIs can be integrated into the same lifecycle as their user-centric APIs. This new category of API tooling should be evaluated by enterprise leadership to determine how it can accelerate their API roadmap.

My hesitation is often due to the use of a code generator to blindly turn data models into an API model. These generators did nothing more than turn DDL into a JSON serialized format. They added no value and often came with no additional business logic – just pure and simple SQL over HTTP.

However, I was recently introduced to a new G2 category, API Generation Software. This category combines elements of code generation with API management and a more customizable approach to API generation. I recently wrote about this new category, including the common capabilities, advantages, and challenges presented by these tools.

In reviewing some of the product offerings in this category, I came to realize that this is not an old-school approach to code generators. Instead, they present opportunities to unlock data from existing systems, drive the generation of API prototypes, and accelerate enterprise integration strategies commonly found within traditional IT departments. Let’s look at each of these opportunities and how this new category of API tools may become a valuable part of your API enablement.

1. Speeding Up Integrations as Part of an EIP Strategy:

Enterprise Integration Platforms (EIPs) play a pivotal role in connecting diverse systems, applications, and data sources within an organization. API generation software complements EIP strategies by:

• Accelerating Development: API generation software expedites the creation of connectors and APIs required for integration, reducing the time and effort needed to implement complex integration scenarios.

• Agility and Scalability: EIPs often require flexibility and scalability to accommodate changing business needs. API generation software provides the agility to respond quickly to new integration demands.

• Reducing Development Overheads: By automating code generation and data mapping, API generation software frees up development resources to focus on strategic integration tasks.

2. Rapid Prototyping of APIs:

One of the most compelling opportunities offered by API generation software is the ability to rapidly prototype APIs. Traditionally, developing APIs could be a time-consuming and complex process, requiring extensive coding and testing. With API generation software, organizations can now create API prototypes swiftly and efficiently, enabling them to:

• Innovate Faster: By reducing the time and effort needed to create APIs, businesses can experiment with new ideas and innovations more rapidly, staying ahead of the competition.

• Validate Concepts: Prototyping allows organizations to validate the feasibility and functionality of APIs before committing to full-scale development, reducing the risk of investing in unsuccessful projects.

• Gather Feedback: API prototypes can be shared with stakeholders and potential users for feedback, ensuring that the final API design aligns with their needs and expectations.

3. Building System APIs:

API generation software is not limited to creating APIs for external consumption. It can also be used to build system APIs that provide access to legacy systems. These APIs:

• Unlock existing systems and platforms: System APIs allow legacy systems and platforms to to expose data through APIs. In some cases, these system APIs provide context to legacy systems that are used for a variety of needs across lines of business. Leveraging API generation software enables context-based system APIs to be generated quickly and easily for use by other teams in the organization.

• Avoiding the need to understand existing systems: System APIs help to abstract the complicated internals of existing systems. Codes can be translated into more meaningful values for use by developers not familiar with the internals of the system.

• Adapting to change: By encouraging integration through system APIs, updates to newer versions can be easily adapted to work with previous API clients. API generation software supports rapidly deploying updates that can contain transformation code to ensure that existing API clients continue to operate as expected while a newer version of the API is generated to take advantage of the latest features of an updated system.

4. Turning Data Sources into Private APIs:

API generation software empowers organizations to turn their data sources into private APIs, unlocking valuable insights and enhancing data accessibility:

• Internal Data Accessibility: Private APIs make it easier for internal teams to access and leverage data from various sources, promoting data-driven decision-making.

• Custom Data Integration: Organizations can create custom data integration solutions tailored to their unique needs and data sources, ensuring data flows seamlessly.

• Data Monetization: Private APIs enable organizations to monetize their data assets by securely exposing them to authorized users or partners, creating new revenue streams.

Conclusion

In the dynamic landscape of modern technology, businesses are constantly seeking ways to innovate, streamline processes, and harness the full potential of their data and applications. API generation software has emerged as a transformative force, opening up a multitude of opportunities that can reshape how organizations operate and thrive in the digital era.

In this article, we explored the exciting new opportunities presented by API generation software, from rapid prototyping to powering EIPs, creating system APIs, and transforming data sources into private APIs. I would encourage you to explore this new category of API tools to see how it could benefit your organization.