In today’s rapidly evolving digital landscape, businesses face constant pressure to adapt or risk being left behind. The strategic use of IT-enabled information management capability (IMC) is no longer just an advantage — it’s a necessity. Companies like Amazon and Meta have reshaped entire industries by effectively harnessing information to implement innovative business models. At the heart of this digital transformation lies a powerful tool: the web API (application programming interface).
The API revolution
APIs have been around since the early days of computing, serving as gateways that allow different software systems to interact. In the context of the web, APIs enable services to be accessible over the internet in a standardized, easy-to-use manner. Think of them as the Lego blocks of the digital world — interchangeable pieces that can be combined in countless ways to build complex structures limited only by imagination.
The modern digital economy thrives on these building blocks. Web APIs facilitate the sharing of functionality and data across platforms, opening up new possibilities for business expansion and innovation. They allow companies to integrate third-party services seamlessly, enhancing their offerings without reinventing the wheel.
For instance, many businesses leverage digital signature services to incorporate electronic approvals into their onboarding processes, eliminating the need for physical paperwork. Health tech startups use APIs from genetic testing companies to accelerate vaccine development by accessing valuable genetic data. These examples highlight how APIs enable businesses to adapt quickly to market needs and provide enhanced value to customers.
Navigating the API marketplace: The ‘mall map’ analogy
Imagine walking into a vast shopping mall without a directory or map. You might wander aimlessly, unsure of where to find the stores you need. This scenario mirrors the challenge many organizations face when trying to discover and utilize APIs within their enterprise. Without a clear catalog or “mall map” of available APIs, developers and product owners can waste valuable time searching for the right services — or worse, end up creating duplicate functionalities.
The mall map serves as an analogy for an organized API catalog or storefront. It provides a clear layout of all available APIs, categorized and easily accessible so that product owners and developers can quickly find the building blocks they need for their next great idea. Just as a mall map guides shoppers to their desired stores, an API catalog directs teams to the services that can accelerate development and innovation.
From chief archaeologist to modern explorer
In the past, discovering existing APIs within an organization often felt like archaeology — digging through legacy systems, documentation, and code bases to unearth reusable components. Some have (maybe just me) even referred to themselves as the resident chief archaeologist, sifting through layers of code in search of hidden treasures. This manual approach is time-consuming and inefficient, akin to wandering the mall without a map.
Fortunately, advancements in technology have provided new tools that transform how we discover and manage APIs. These solutions move beyond the archaeology aspect, offering sophisticated “mall maps” for the API ecosystem. They provide features like automated discovery, cataloging, and documentation, enabling organizations to have a comprehensive view of their API landscape. Developers no longer need to be archaeologists; instead, they can become modern explorers, leveraging these platforms to find and integrate APIs effortlessly.
Challenges in API adoption
Despite the clear benefits, many large enterprises struggle to fully embrace the potential of APIs. In our own research, where we surveyed enterprise-wide API developers, several major challenges emerged:
- Lack of knowledge sharing and discovery tools. A significant number of developers highlighted the absence of a centralized API catalog or knowledge base as a primary barrier. Without an accessible repository, developers are unaware of existing APIs that could be reused.
- Organizational commitment and evangelism. Many respondents pointed out that a lack of management support and organizational commitment hampers API reuse. Without leadership promoting the value of APIs, teams often work in silos, leading to duplication of efforts.
- Inconsistent API design practices. Developers noted that inconsistent standards and lack of clear guidelines make it difficult to understand and integrate existing APIs. This inconsistency leads to increased complexity and reluctance to adopt APIs developed by other teams.
These challenges align closely with the recommendations outlined in this article. Addressing them requires a strategic approach that encompasses taxonomy development, tool adoption, and cultural change.
Building an effective API taxonomy
A crucial step in overcoming these challenges is developing a clear taxonomy for APIs. This involves categorizing APIs based on several key factors:
- API classification. Defines the primary purpose or functionality of the API. Examples include:
- Experience APIs: Tailored to specific user experiences or devices.
- Integration APIs: Facilitate interactions between different systems.
- Data APIs: Provide access to raw data.
- Orchestration APIs: Combine multiple services into a single, unified response.
- Facade APIs: Simplify complex services or protocols, improving usability.
- Workflow APIs: Manage multi-step processes with individual states.
- Search APIs: Enable querying and retrieving data based on specific criteria.
- API audience. Identifies who the intended consumers of the API are. This classification is adapted from Zalando’s RESTful API guidelines:
- Internal-Component: Used within a specific component or application.
- Internal-Business Unit: Shared within a particular business unit.
- Internal-Company: Accessible across the entire organization.
- External-Partner: Shared with business partners.
- External-Public: Available to external developers and the public.
- Data classification. Categorizes the sensitivity and confidentiality of the data handled by the API:
- Public: Openly accessible information.
- Internal: Restricted to the organization.
- Confidential: Sensitive information requiring strict access controls.
- Restricted: Highly sensitive data with stringent access limitations.
- Data protection requirements. Specifies compliance needs related to data residency and protection regulations, such as GDPR or country-specific laws.
By applying this taxonomy, organizations can improve API discoverability and ensure that developers understand the context and appropriate use of each API.
Strategies for effective API utilization
To avoid disruption and stay competitive, organizations need to develop a comprehensive API strategy that addresses these challenges. Here are key considerations for leveraging APIs effectively:
- Develop a clear taxonomy and documentation. As outlined, creating a standardized language and classification system for APIs enhances discoverability and understanding. Comprehensive documentation ensures that APIs are accessible and usable by those who need them.
- Implement a centralized API catalog (your “mall map”). A centralized repository or catalog serves as the “mall map” for your API ecosystem. This digital storefront enables developers and product owners to browse available APIs, understand their capabilities and determine how they can be integrated into new projects.
- Leverage advanced discovery tools. Modern tools can automate the discovery and documentation of APIs within your organization. These platforms go beyond manual methods by scanning your systems to identify existing APIs, mapping out their connections and highlighting opportunities for reuse.
- Adopt key API design principles. Implementing foundational principles can guide the development of high-quality, reusable APIs. Below is a table outlining 10 principles to consider.
| Principle | Details |
| P1. Consumer-focused interfaces | Design APIs that match the user’s language and usage patterns. Ensure message formats and patterns align with users’ mental models. Use consistent naming (singular vs. plural nouns) and align APIs with user experiences (e.g., integration, search). Use appropriate HTTP verbs to convey actions rather than including verbs in the URL (e.g., GET /accounts vs. POST /getAccounts). |
| P2. Consistency and standards | Maintain consistency in API signatures (URI, query parameters) and use of standard HTTP verbs. Use consistent vocabulary across APIs. Ensure documentation and support tools are comprehensive and uniform. |
| P3. Flexibility and efficiency | Ensure APIs are suitable for both first-time and experienced users. Avoid “chatty” APIs that require multiple requests for common tasks. Make it obvious which endpoints to use for specific actions. |
| P4. Clear error handling | Provide error messages that cater to both machine and human audiences. Include machine-readable information and sufficient details for correction. Use appropriate HTTP error codes (e.g., 4xx for client errors, 5xx for server errors) and ensure response codes match the use case. Avoid using 200 OK with error messages. |
| P5. Versioning and deprecation | Make API versioning mandatory and include vitality and deprecation information in the design. Maintain backward compatibility where possible. Follow versioning guidelines to manage changes effectively. |
| P6. Comprehensive documentation | Ensure all information is easy to search and focused on user tasks. Use standardized specifications like OpenAPI to include proper metadata. Define operations, parameters, and base paths, and reuse components where possible. Provide examples, expected headers, security schemes, and property restrictions (e.g., field length, data types). |
| P7. Protect sensitive data in URIs | Do not expose personally identifiable information (PII) through URIs, including paths or query strings, as this data can be inadvertently exposed through logs. Use opaque identifiers in URLs. Ensure records adhere to privacy policy standards. |
| P8. Security first | Implement robust security measures, including authentication, authorization and access control. Protect APIs with appropriate tokens and policies. Avoid returning system information like database errors or stack traces. Clearly define how both server-to-server and user-to-server authentication and authorization are handled. |
| P9. Health and status endpoints | Include /health endpoints for basic health checks and /status endpoints for deeper system validation. Ensure that these endpoints help in monitoring and failure diagnosis. Define how failures are addressed and communicated. |
| P10. API reusability | Design APIs with reusability in mind, enabling them to serve different applications. Before creating new APIs, evaluate existing ones for potential enhancement. Consider how many applications or systems will consume the API and the prospects for expanding its use in the future. |
- Foster a culture of knowledge sharing. Encouraging collaboration between teams and promoting the value of API reuse can lead to more efficient development processes. Leadership should actively support these initiatives, providing resources and recognition to teams that contribute to and utilize shared API assets.
- Invest in API governance and management. Establishing governance practices ensures that APIs are consistently developed, maintained and retired when necessary. This includes setting standards for security, performance, and compliance. Effective management of the API life cycle helps maintain the quality and reliability of services offered.
The role of organizational commitment
Successfully implementing an API strategy goes beyond technology — it requires organizational change. Top management support is essential to driving the adoption of best practices and allocating the necessary resources. This includes:
- Evangelism and leadership. Leaders should act as champions for API reuse, communicating its benefits, and setting expectations across the organization.
- Training and awareness. Providing education and training opportunities helps developers understand how to create and consume APIs effectively.
- Process integration. Incorporating API reuse considerations into project planning and development processes ensures that reuse a standard part of how work gets done.
Benefits of embracing APIs
When organizations overcome the hurdles and fully leverage APIs, the rewards are significant:
- Increased agility. APIs enable faster responses to market changes by allowing businesses to integrate new functionalities and services quickly.
- Cost efficiency. Reusing existing APIs reduces development time and costs associated with building new capabilities from scratch.
- Enhanced innovation. APIs open doors to new business models and revenue streams by facilitating partnerships and integrations with external services.
- Improved customer experience. By combining various services through APIs, companies can offer more comprehensive and personalized solutions to their customers.
Start your journey today
In an era where digital transformation is reshaping industries, the strategic use of APIs is a powerful lever for businesses to avoid disruption and stay ahead of the curve. By developing a robust API strategy that includes a clear taxonomy, centralized discovery platforms (your “mall map”), a culture of knowledge sharing and strong organizational commitment, companies can unlock the full potential of their IT-enabled information capabilities.
Developers or architects no longer need to serve as resident chief archaeologists, painstakingly digging through code bases to find reusable components. With advanced discovery tools moving beyond manual archaeology, organizations now have the means to efficiently map out and leverage their API assets.
By embracing these principles and strategies, businesses can transform their approach to innovation and growth. APIs are more than just technical tools — they are enablers of a dynamic, responsive, and collaborative enterprise. Those who recognize this and invest accordingly will be well-positioned to navigate the challenges of the digital economy and capitalize on the opportunities it presents.
The path to effective API utilization begins with understanding and applying these foundational principles. By addressing the major challenges highlighted in our research — such as the need for a unified taxonomy, better discovery tools, and organizational commitment — organizations can create an environment where innovation thrives. Use the provided principles and taxonomy as a starting point to assess and enhance your current API strategies. With commitment and the right tools, your organization can become more agile, efficient, and ready to meet the demands of the digital future.
Shawn McCarthy is vice president and chief architect, Global Architecture, Risk & Governance, at Manulife.
This article was made possible by our partnership with the IASA Chief Architect Forum. The CAF’s purpose is to test, challenge and support the art and science of Business Technology Architecture and its evolution over time as well as grow the influence and leadership of chief architects both inside and outside the profession. The CAF is a leadership community of the IASA, the leading non-profit professional association for business technology architects.
—
New Tech Forum provides a venue for technology leaders—including vendors and other outside contributors—to explore and discuss emerging enterprise technology in unprecedented depth and breadth. The selection is subjective, based on our pick of the technologies we believe to be important and of greatest interest to InfoWorld readers. InfoWorld does not accept marketing collateral for publication and reserves the right to edit all contributed content. Send all inquiries to doug_dineley@foundryco.com.