APIs are everywhere and power almost everything. API usage and traffic continue to grow as applications become more distributed, thanks to the massive amount of SaaS and other web-based services that consume the modern software landscape. APIs offer significant advantages to developers, empowering them to leverage existing functionality, accelerate application development, and unlock new possibilities. However, as applications and API portfolios become increasingly complex, maintaining a comprehensive understanding of all existing APIs becomes a significant challenge. APIs can quickly become obscured or forgotten in the sprawling landscape of microservices and interconnected systems.
This lack of visibility creates potential problems. It can lead to redundant development efforts, hinder efficient code reuse, and pose security risks if hidden or undocumented APIs contain vulnerabilities. This is where API discovery can lend a helping hand. API discovery is a crucial process for developers and security teams to identify, catalog, and assess APIs. The benefits of leveraging API discovery include better API governance, supporting informed decision-making about API usage, and helping proactively mitigate security threats.
In this blog, we'll explore the fundamentals of API discovery, including what it means, techniques for identifying documented and hidden APIs, and the importance of discovery for security and efficiency. Lastly, we will briefly look at tools to streamline the process, including StackHawk's API discovery capabilities. Let's get started!
What Does API Discovery Mean?
In the most basic terms, API discovery is the process of identifying, documenting, and understanding the APIs within a specific environment. As APIs are discovered, they could be APIs developed internally, those provided by third-party providers, and, most crucially, APIs that may be hidden or undocumented.
It makes sense to think of API discovery as creating an up-to-date inventory of all the APIs or, more broadly, digital "connection points" within your systems. The API discovery process involves uncovering details such as:
Endpoints: The URLs that applications use to interact with the API.
Methods: The supported actions (GET, POST, PUT, DELETE, etc.).
Parameters: The data an API can accept and the responses it generates.
Authentication/Authorization: How the API ensures only permitted users or applications can access it.
Why It Matters for Developers
Regarding why API discovery matters, there are many reasons why it can be helpful to developers and organizations. Some of these benefits include:
Prevents Reinventing the Wheel: Discovery can enhance API visibility, revealing existing APIs that solve the problem you're tackling, saving you development time and resources.
Promotes Innovation: Knowing what APIs are available unlocks new ideas for applications and integrations.
Simplifies Collaboration: A shared API catalog facilitates teamwork by allowing teams to reuse well-defined APIs across projects.
In addition, having a complete API inventory allows organizations to understand what APIs are in use and which are not. If an API is not in use and not maintained, it could present a major security risk that may be unknown if the API wasn't uncovered as part of the discovery process. Big or small, if you are using and building APIs, API discovery should be part of your toolkit.
What Makes an API Discoverable?
Discovering APIs involves many potential processes, which we will discuss in the next section. However, it's important to first consider some factors that make an API discoverable. Let's examine a few best practices and key facets that make APIs discoverable.
Clear and Comprehensive Documentation
Well-written documentation is the cornerstone of API discoverability. It should provide a thorough overview of the API's purpose, how to use it, the different methods it supports, the parameters it accepts, expected responses, potential error codes, and even illustrative examples. Think of this documentation as a user-friendly guidebook for your API. This point also includes following well-known documentation practices, such as creating an OpenAPI Specification (OAS) for your APIs.
Developer Portals
If you want to make an API easily discoverable, exposing it through a developer portal is a great idea. A developer portal is like a central marketplace for your APIs. It lists available APIs, provides powerful search functionality, and often includes features to try out the APIs interactively, such as Swagger UI. This enables developers to find the API they need quickly and experiment with it easily.
Descriptive and Standardized Naming Conventions
Consistent naming conventions for endpoints and parameters significantly aid discoverability. Naming and parameters should be predictable and easily allow developers to understand your API's structure. On top of consistency, using meaningful names helps developers anticipate the functionality of an API even before they've read the complete documentation.
Adherence to Design Standards
Employing widely adopted standards like REST or GraphQL makes your API more predictable for developers. These standards lay out common patterns and expectations, reducing the learning curve for developers integrating with and using your API and improving discoverability.
These points reflect more of a manual approach to API discovery. In these cases, following the above guidelines allows developers, internal or external, to quickly see what APIs are available and will enable them to use the APIs effectively. But what about discovering hidden APIs? This is where automation can come in handy. Next, let's compare automated and manual API discovery.
Manual vs. Automated API Discovery
As alluded to, there are two primary ways to approach API discovery. Both have particular use cases and methods associated with them. Let's look at the differences between manual and automatic API discovery tools and techniques.
Manual Methods
Manual methods are likely familiar to developers who use APIs. Many of these methods require a technical background and focus on discovering APIs before using them or figuring out which ones are currently used within a codebase. Here are a few ways developers can manually discover available or in-use APIs.
Code Review: Carefully scrutinizing source code to identify how APIs are defined and used.
Network Traffic Analysis: Inspecting network packets to trace communication patterns between applications, revealing API usage.
Referencing Existing Documentation: Reviewing any available API documentation, system architecture diagrams, or developer notes.
These manual techniques are helpful in specific scenarios but have limitations. They can be labor-intensive and time-consuming and are prone to missing hidden APIs that don't leave clear traces in code or network traffic.
Automated Methods
Specialized API discovery tools need to be used for automated methods of API discovery. These can involve tools built into API management platforms, API security platforms, and other tools that support discoverability. These tools are built to scan systems, analyze network patterns, and even probe endpoints to actively uncover APIs. They provide a comprehensive, scalable, and efficient way to identify documented and hidden APIs.
Most of the tools available to leverage automated API discovery are within API management and security platforms.
API Management Platforms and Gateways: Gateways, such as Kong or Apigee, often include API discovery capabilities, as they control traffic and offer insights into API usage.
Security Scanners: Specialized tools like StackHawk proactively scan for vulnerabilities and map your API endpoints, exposing previously unknown ones.
Automated API discovery tools often offer organizations a significant advantage in maintaining a complete and up-to-date understanding of their API inventory and improving their API security posture. Next, let's explore the benefits further by looking at what makes API discovery important for modern organizations.
The Importance of API Discovery
API discovery plays a vital role in managing, securing, and maximizing the potential of your API infrastructure. From developers to those involved with the business and compliance side of an enterprise, API discovery offers a wide array of benefits. Here's a breakdown of some of the key areas where API discovery can have an impact.
Security Vulnerability Detection: API discovery lets you gain comprehensive visibility into all the APIs used within your environment. This includes undocumented or forgotten endpoints ("shadow APIs") that are prime targets for attack. Maintaining an accurate API inventory reduces the attack surface and proactively addresses potential BFLA, BOLA, and other vulnerabilities outlined in the OWASP API Top Ten.
Improved Compliance: Industries governed by regulations, like healthcare with HIPAA or finance with PCI DSS, frequently have strict requirements for sensitive data access and control. API discovery helps you map the flow of data within your APIs, simplifying the process of demonstrating compliance with these various regulations.
Reduced Development Friction: API discovery facilitates faster and more efficient development practices. By making it easy for developers to locate and understand existing API functionality (both internal and third-party), they avoid reinventing the wheel and duplicating API functionality.
Accelerated Innovation: A catalog of discoverable APIs empowers developers to create connections between services rapidly and allows developers and architects to understand existing capabilities available within the enterprise. Knowing what APIs are available and their capabilities results in a faster and easier path towards innovation.
Partnership and Ecosystem Development: API discovery is vital for onboarding partners if you will have third-party users of your APIs. Well-documented and easily discoverable APIs can open business opportunities and enable external developers to use them and collaborate with your organization seamlessly.
Incorporating API discovery into your API development lifecycle and security practices is essential for building robust and secure applications. From a security perspective, one of the biggest downfalls of not using API discovery tools is that hidden APIs may expose vulnerabilities you're unaware of. Next, let's take a look at what the different types of hidden APIs are and the impact they can have.
What Are the Different Types of Hidden APIs?
Hidden APIs are those that exist within a system but are not cataloged or included in the official documentation. Such APIs can become a significant security and management concern since they may slip through the cracks of security testing and patching. Here are some common types of hidden APIs to be aware of:
Shadow APIs
These are unintentionally exposed APIs, often created by developers during testing or for temporary purposes. Shadow APIs might not follow established security standards or documentation practices, leading to potential vulnerabilities being exploited by attackers.
Zombie APIs
These are obsolete or deprecated APIs meant to be decommissioned but remain active within a system. Poor versioning practices and tracking of decommission processes lead to these APIs remaining in the mix of available APIs and represent potential security risks if not properly patched or removed.
Rogue APIs
These APIs are deliberately created and hidden, often with malicious intent. As a backdoor into the system via API, a rogue API may be designed to circumvent security controls or exfiltrate data without authorization.
API discovery tools can help uncover hidden APIs and remedy any security vulnerabilities present within them. The security risks of these APIs can be widespread and leave a massive hole in your security efforts. With that in mind, let's dig a bit further in the next section on those specific security risks.
Security Risks of Hidden APIs
As mentioned, hidden APIs pose a significant API security challenge because they often exist outside standard security monitoring and governance practices. Even the best security practices are null and void if certain APIs completely escape the umbrella of coverage. By having hidden APIs existing in your portfolio, here are some of the key risks they introduce:
Unpatched Vulnerabilities: Hidden APIs may contain undetected and unpatched vulnerabilities, especially zombie APIs that are no longer actively maintained. This makes them easy targets for attackers.
Expanded Attack Surface: Hidden APIs increase the available attack vectors for malicious actors to exploit. They may discover these APIs through trial and error, code leaks, or automated scanning.
Data Exposure: Poorly secured or undocumented APIs can be gateways for unauthorized data access or leaks. Attackers may use hidden APIs to retrieve sensitive data or manipulate the system unnoticed.
Compliance Violations: Hidden APIs can lead to non-compliance with data privacy regulations like GDPR or industry-specific standards. This is because ensuring proper authorization and access controls on undocumented APIs becomes difficult as there is minimal oversight on them.
With these factors in mind, it's easy to see why proactive discovery of hidden APIs is essential. By keeping track of every single API within your organization's API portfolio, you enhance your capabilities for mitigating these risks and maintaining a strong security posture.
