API Lifecycle Management

Building an Inventory


Maria Teresa Pereira is a Cyber Threat Hunter at Siemens Energy. In addition to cybersecurity, her past experiences include process automation and backend development. She discusses effectively building an API inventory and documenting APIs in this article.

APIs are the heart of the ongoing enterprise digital transformation, acting as channels for communication and data exchange between software systems and IoT devices. So, to properly secure APIs, we must consider three pillars: governance, testing, and monitoring.

API inventory is an integral part of API governance and security. It provides the foundation for understanding, managing, and securing your organization’s APIs. Organizations can implement effective security controls to protect their data in an API-driven environment by maintaining a well-organized API inventory.


API Inventory

One might think that inventory management is an old hat. But in the cybersecurity world, one ultimate truth applies in every scenario: you can’t secure what you can’t see. This is where the creation and maintenance of an API inventory comes in. APIs come in many shapes and sizes, and to create a proper inventory, we need to catalog and classify them according to their risk. An API inventory is an up-to-date structure and centralized catalog of all your organization’s external and internal APIs.

There are some key components that an API inventory should include, namely, information about each API, such as the name, the description, the purpose, the owner, any version, and any details on the version, including changes and updates. If you have any integration with third-party APIs, you should also include that information. Information on the API endpoints, the purpose of each endpoint parameters, requests, responses, and other API details such as authentication, authorization, dependencies, etc, must also be included.


Importance of API Inventory

Developers have long owned and developed APIs, often for internal consumption, with little or no security oversight. APIs are deployed externally as they have become more integral to the business. The act of tracking them and securing them continues to lag in many organizations as we can see by recent security incidents. When all the API versions are not properly retired or locked down, they may have security holes that malicious actors can exploit. Organizations can greatly reduce the risk of their attack surface by keeping an accurate API inventory and using good version control.

An API inventory gives you a handle on your attack surface and exposure. You can track all the APIs used by your applications, see who owns each one, track all the versions of APIs, and identify zombie and shadow APIs.

To study the importance of having an API inventory, let’s study a real-world data breach. Optus is the second-largest telecommunication company in Australia. In September 2022, the company has suffered a data breach, which exposed almost 10 million customer records – I mean, this is 1/3 of Australia’s population.
Some information illegally obtained included names, birthdates, home addresses, passports, driving license numbers, Medicare numbers, and emails, among other data. An attacker discovered an API used for testing unknowingly exposed to the internet using real customer data. Besides being exposed to the internet and using real customer data, this API, also called Shadow API, did not require any authentication or authorization. Besides, the API did not have any monitoring

API Discovery

API discovery is the process that helps organizations identify, catalog, and manage their APIs. API discovery often involves inserting documentation, exploring developer portals, and using specialized tools to identify and evaluate APIs based on criteria. Regarding API discovery, you have two ways to do this: automated and manual. In an automated way, you’ll use specialized tools, scripts, and services to scan websites, applications, and network traffic for API endpoints. In manual API discovery, you’ll be reviewing documentation. You’ll be checking for API-related URL patterns and network traffic. You’ll analyze source code, explore API directories, and ask developers to collaborate with other teams if available.

Manual API discovery is suitable when you have a limited scope. The level of precision will be very high because you will be carefully examining and validating each API you find. But you have to be aware of the disadvantages as well. It is a time-consuming task. There is a risk of human error. This task depends on the expertise of the person who is performing it.

When it comes to automated API discovery, you have some advantages as well. Using automated scans to perform API discovery is very effective, saving time. But you have some disadvantages as well. The scanners that you use don’t have a context on the application where you’re searching for APIs. So, you must be aware and remember that you might have some false positives on the way.

In practice, a balanced approach that combines manual and automated discovery might be the most effective strategy. Manual validation can follow automated scans to ensure accuracy and address any nuances that the scanner misses.

API Documentation

API discovery helps users find your API, and proper documentation will show them how to use it once they have found it.

A good API should serve a specific purpose. Good API documentation should include an overview of the API, a Getting Started Guide, authentication information, information about endpoints, requests and response formats, parameters, information on the status codes that you might be expecting when using the API, information on the version of the API, testing instructions, use cases and best practices. It should contain contact information in case the consumers using the API have any doubts about it.

An element of API documentation is an API reference documentation. An API Reference Guide is a human-readable document that provides detailed information about the API. It provides technical details about the APIs, such as the methods, parameters, responses, and status codes.

It can be easily generated with a tool like Swagger UI, based on OpenAPI specification. The OpenAPI specification, formerly known as swagger, is a powerful way to document your APIs in a standardized and machine-readable format. OpenAPI provides a standard way to describe the rest of APIs.

API Marketplace

An API marketplace is a large platform that houses multiple APIs and allows developers to discover, evaluate, and integrate APIs. It also includes API documentation as part of the package. An API marketplace brings API buyers and sellers together in one platform. It allows API providers to list their APIs and monetize them by offering different subscription plans.

Identifying hidden APIs

There are five ways in which you can identify hidden APIs.

  • Use manual methods like network traffic analysis and browser developer tools.
  • Employ automated tools for API discovery and web scraping
  • Actively explore web pages, examine source code, and perform security testing
  • Check for API documentation, open API specification, and other public repositories that might exist about that API.
  • Engage with developer teams and collaborate with other teams and the community.

API security is a continuous and evolving process due to the dynamic threat landscape and changes in the API lifecycle. It requires ongoing monitoring and collaboration to maintain a strong security posture throughout the API lifecycle. In essence, you need to consistently and continually depend on these three pillars to secure one of your most important assets: your APIs.

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture