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

APIs are everywhere, and they 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, and it can refer to the discovery of both internal and external APIs. And you should undertake that API service discovery for plenty of reasons.

Some businesses use API discovery, for example, 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. API discovery can help to identify any such APIs so the organisation can deal with them appropriately.

Other businesses use API discovery for project efficiency to avoid diff teams reinventing the wheel when working on company projects. In large enterprises, it’s often the case that different teams develop APIs. API discovery can help those teams to find out what already exists within the business in terms of APIs that might be usable by multiple departments.

Then there is external API discovery. Say a business wants to provide an interactive map and route planning functionality on its website or within its app. It has the choice to develop this functionality in-house or to search for an API that can provide it. Discovering the latter can mean saving a great deal of time and effort.

The importance of API discovery

There are important reasons for using API discovery in each of the above examples.

Let’s take the first instance – that of a company seeking to discover any shadow, rogue or zombie APIs that may be operational. Such APIs pose various threats. They could mean that company data is accessible when it shouldn’t be, meaning data security could be compromised. They could also deliver a poor user experience, with nobody maintaining or monitoring them. 

On the other hand, companies using internal API discovery for project efficiency stand to benefit in several ways. The better use of resources and enhanced collaboration that API discovery facilitates means the business can save money on developer time and resources and get to market faster.

This is true for businesses using external API discovery, too. 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 financial rewards that result from this.

Why is API discovery important for a software tester?

One other important use case for API discovery is that of software testing. Finding the right APIs to help with their work means that software testers can undertake their tasks faster and more efficiently. This can speed up the testing process, meaning a faster time to market while still ensuring the same rigorous testing quality. API discovery can also help software testers ensure they are using the most recent version of an API when undertaking their work. It can also flag any new APIs that may introduce further efficiencies into their processes.

Of course, software testers may test APIs themselves, as well as other pieces of software. In this case, automated API discovery tools may help them, as some can identify which forms of sensitive data an API can access. This can help the software tester to identify any vulnerabilities and security concerns as part of their work.

What is service discovery in microservices? 

Service discovery and API discovery are not the same things. 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 an API gateway for microservices 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.

Is an API gateway the same as service discovery?

We’ve mentioned an API gateway in the context of microservices, as using an API gateway for microservices can deliver plenty of benefits. But an API gateway is not the same as service discovery. A gateway can facilitate service discovery, certainly. Tyk API Gateway, for example, allows you to configure service discovery using the Dashboard, where you can enable it using any service that returns a JSON object.

Yet there is far more to using an API gateway than service discovery alone, as it quickly becomes apparent when you start exploring the benefits of Tyk. This API management open source approach delivers security, code precision, scalability, faster time to market, and so much more, putting the service discovery vs API gateway debate rapidly to bed. 

Types of API discovery 

There are various ways that you can approach API discovery, with a range of tools on the market to support you in your efforts. Broadly speaking, though, API discovery can be broken down into two main types: manual discovery and automatic discovery. The type that you choose will depend on your business needs and budget.

Manual vs automatic API discovery

Manual API discovery, as the name suggests, involves developers manually searching for APIs. They can do so by searching online through API directories and documentation. Developer communities may also facilitate manual discovery by providing word-of-mouth recommendations.

While manual API discovery may be ideal for businesses seeking a single API in order to achieve a particular task, the time-consuming nature of the task means that those with more complex needs are likely to opt for automatic discovery. 

Automatic API discovery 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. API discovery tools such as these can maximise efficiency when it comes to finding the perfect API. 

How to make your API discoverable 

API discovery doesn’t only benefit those businesses looking for APIs but also those selling them. This is why it’s so essential to make your API discoverable. After all, if people can’t easily find it, they are unlikely to use it – at least not without extensive time and effort by your marketing team.

Documentation is critical to making an API discoverable, whether by external parties or other teams within your business. Documenting your API correctly makes it easy for people to find out what it does and how. Building using OpenAPI standards is a good idea in this respect, as the clear documentation format underpins this approach for maximum discoverability.

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

Ultimately, if you make it easy for people to find your API and take a self-service approach to consumption, you’ve done plenty in maximising the chances of your API product’s success.

The industry standard for API discovery

There are plenty of API discovery tools on the market. Some will scour API directories based on specific criteria and keywords to find the perfect API. Others will scan your traffic to identify instances of API calls going through your network and then establish where those calls go.

The gold standard for API discovery, though, is a tool that doesn’t just involve discovering APIs but that also delivers added value. In the case of a discovery tool that scans your network traffic, for example, one that can identify if sensitive data has been accessed provides a distinct advantage.

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 and then understand and interact with only a minimal amount of implementation logic.

Factor API discoverability into your approach

Working with APIs raises many questions, from which API management architectural and deployment patterns to use to how to get the best out of your API security platform to keep your regulators happy and ensure you have sufficient peace of mind to sleep at night.

By factoring API discovery into your approach, you can lay the foundations for taking your projects to the next level. API discovery can ensure you don’t have hidden security vulnerabilities due to zombie, rogue or shadow APIs while also enhancing the efficiency of your internal operations. Using an open source API gateway such as Tyk can also ensure that you tick service discovery off your list when working with a microservices architecture.

Finally, API discovery can ensure that you explore a wide variety of APIs so that you can undertake each and every project in the most efficient manner possible. Doing so will ensure you keep your developers happy, control your budget, and achieve time to value as rapidly as possible. With all of these benefits to be gained, isn’t it time you focused some thought on how to approach API discovery for your business?