How to Discover and Document Your API Landscape

PUBLISHED ON January 8, 2024
LAST UPDATED Jan 08, 2024

API security is more than a tool or a one-off project. Attacker tactics and techniques, and your API landscape, are both in constant flux – changing and evolving all the time. Your defense needs to be just as dynamic. And that includes keeping up with what APIs you have, where they are, and what they do – both those that are externally facing and those that power internal services.

That is easier said than done, but we offer some good places to start below.

Get our new guide that walks you through getting started with API security.

Discover and document your internal and externally facing APIs

The proliferation of APIs across a distributed infrastructure inevitably leads to API sprawl, and most organizations don’t know how many APIs they have or how they’re used. Developers often stand up new APIs or reuse existing ones, but much of this is out of sight of security. As a result, the attack surface created by APIs is significantly larger than most organizations realize.


When conducting API discovery, consider, for each API:

  • Is it public or private?
  • Is it external or internal?
  • Who owns it?
  • What kind of calls can it make?
  • What is the intended use case?
  • How is it written? (JSON, XML, GraphQL)
  • What kind of data is it transmitting?


Once you have an inventory of every API in your environment, it’s time to document and catalog them. This involves understanding the code behind each API. Ideally, each API has an API schema that provides definitions of acceptable use for that API, including what can be exposed, what methods can be used, what are the parameters, keys that enforce utilization, etc.

However, you’re likely to find that few APIs actually have defined schemas, and you will need to develop schemas as your API security program matures. While not all API protocols have easily definable specifications, the vast majority of APIs currently deployed are RESTful APIs and can be described by an OpenAPI Specification and defined in a JSON schema.

Discovery and documentation can be performed manually or automated with a tool. The best mode of discovery is real-time analysis of the traffic hitting your endpoints. With this data, you can prioritize security efforts on APIs getting traffic. Analytics can identify which endpoints are no longer used and which clients are still actively using old endpoints. Once you know which API endpoints are serving responses, take a hard look at what’s deployed and exposed, and compare your actual attack surface with your theoretical API inventory.

After you complete the initial discovery and documentation, shift these documentation functions left, being careful not to slow down development. For example, for RESTful JSON endpoints, you can easily generate an Open API 3.0 schema file from your CI/CD pipeline that will define, in excruciating detail, what is and isn’t expected. A tool with OpenAPI schema support functionality can compare what your build system thinks is in your environment with what’s actually there, allowing you to quickly pinpoint undefined or unspecified functionality.

Address Zombie and Rogue APIs

It is likely that the discovery process will uncover some APIs that were previously unknown. Like shadow IT, rogue or shadow APIs are those that exist outside of an organization’s official security and operational maintenance processes. Countless scenarios can lead to a rogue API.

For example, a developer may quickly stand up an API to resolve a problem or to develop a proof of concept for a larger project. Similarly, zombie APIs are APIs that were previously valid and approved but were eventually abandoned or replaced by newer versions. If the old APIs aren’t properly removed from production, they can leave organizations with outdated, vulnerable points attackers can exploit.

Learn more about zombie and rogue APIs.

To address zombie and rogue APIs, you need visibility, governance strategies, documentation, and communication between development and security teams.

Specifically for zombie APIs, make sure you have proper versioning and defined processes and procedures for decommissioning old or unused APIs. For rogue APIs, ensure you have a strategy and process to enforce how and why an API gets deployed with the proper security controls. Think ownership, documentation, access, authentication, etc.


About the Author

Bret Settle

Bret has served in multiple executive roles for Corporate Express/Staples and BMC Software and has extensive knowledge of the software development and security products industries. Bret has been responsible for enterprise security in multiple roles and has been an innovator throughout his career and has a proven track record of building and developing high performing organizations and dynamic cyber security teams.