API discovery: what is it and how does it work?

APIs are connecting the world. But how do you find them and uncover what they do? This is where API discovery comes in. 

What is API discovery? 

API discovery is the process of searching for and finding API resources. It covers both internal and external APIs. 

Why use API discovery? 

You can use API discovery to: 

  • Find rogue and zombie APIs – all those old versions that should have been taken offline and decommissioned but, for one reason or another (personnel changes or forgetfulness, usually), remain operational.
  • Ensure project efficiency and avoid different teams reinventing the wheel when working on company projects. API discovery can help engineering and security teams find out what already exists within the business that might be reusable.
  • Develop functionality. Say you want to provide an interactive map and route planning functionality via your website or app. You can develop this functionality in-house or search for an external API that provides it. Discovering the latter can mean saving a great deal of time and effort.
  • Test software. Finding the right APIs to help with their work means software testers can undertake tasks faster and more efficiently. This can deliver a faster time to market while still ensuring rigorous testing quality. API discovery can also help software testers ensure they are using the most recent version of an API, as well as flag any new APIs that may introduce further efficiencies.

Note that software testers may test APIs themselves. In this case, automated API discovery tools can help; some can identify which forms of sensitive data an API can access. This can help the software tester identify security vulnerabilities and concerns.

The benefits of API discovery

The above examples highlight some important reasons for using API discovery.

Discovering shadow, rogue or zombie APIs is the first step in neutralising the threats these APIs pose. They could, for example, compromise data security by making company data accessible when it shouldn’t be. They could also deliver a poor user experience, with nobody maintaining or monitoring them. 

Companies using internal API discovery for project efficiency enjoy better use of resources and enhanced collaboration, enabling them to save money on developer time and resources and get to market faster.

The same is true for businesses using external API discovery. By finding and using an existing API to embed certain functionality, a business can save money and develop its product(s) faster, getting to market sooner and enjoying the resulting financial rewards.

Types of API discovery 

Broadly speaking, API discovery can be broken down into two main types: 

  • Manual API discovery – this involves developers manually searching for APIs through directories, documentation and word-of-mouth recommendations.
  • Automatic API discovery – this involves using tools that scan and index APIs. These tools are faster than manual methods. A discovery API is one such example. It can enable developers to search for APIs based on criteria such as functionality, tags and keywords. 

How to make your API discoverable 

API discovery benefits businesses selling APIs. Documentation is critical to making an API discoverable, making it easy for people to find out what it does and how. 

Listing your API with directories is a must, as is ensuring your API is machine readable. After all, it may be a computer trying to discover what your API is about rather than a human. Also making your website SEO-friendly will ensure all bases are covered.

API discovery tools

Some API discover tools scour directories based on specific criteria and keywords. Others scan your API traffic to identify instances of API calls going through your network, then establish where those calls go. Some of these can also identify if sensitive data has been accessed.

The industry standard in making APIs discoverable, meanwhile, is the OpenAPI Specification. This defines a standard, language-agnostic interface to HTTP APIs, meaning that humans and computers can discover, understand and interact with only a minimal amount of implementation logic.

Is service discovery in microservices the same as API discovery? 

Service discovery and continuous API discovery are not the same thing. Service discovery in microservices is about locating available services within a microservices architecture. That means dealing with a dynamically changing upstream service set across independent microservices. 

A client uses service discovery functionality to find the service it needs within containerised environments where various factors (such as the number of service instances) can change dynamically.

With a microservices API gateway added into the mix, service discovery can be combined with other functions to deliver a more robust service. For example, combining service discovery with a circuit breaker makes it possible to easily detect and discover failures at the gateway level when load balancing between multiple Docker containers. When a container fails and a new service spawns on a different IP address, the service discovery functionality can detect the failure and reconfigure itself without the need for manual intervention.

Need more input? Why not browse the Tyk Learning Centre to see what you can discover?