How to improve API discoverability with Postman workspaces

One of the best ways for API producers to improve their API distribution strategy is to invest heavily in the discoverability of their APIs. APIs should be visible, searchable, and easy for developers to find and work with. Additionally, API integration should be a seamless process that doesn’t require the API consumer to regularly consult with the API producer.

In this article, we’ll discuss the concept of API discoverability in more detail—with a focus on who needs to discover APIs. After that, we’ll explore Postman workspaces and review how these collaborative spaces for API-related work improve API discoverability.

What is API discoverability, and why is it important?

API discoverability refers to the ease with which developers can find, understand, and use APIs. It encompasses the developer experience of an API from discovery, exploration, and usage.

Organizations can increase the adoption rate of their APIs when they invest in making them more discoverable. Additionally, APIs that are easy to find and understand are more likely to be used and recommended by developers. APIs are a huge revenue source for many companies, and more API adoption and utilization can directly translate to more revenue.

Who needs to discover APIs?

The types of consumers who need to discover an API can vary widely based on the API’s use case, but they typically fall into one of the following three categories:

• Internal developers: Large organizations often have multiple teams that work on different APIs. It is therefore important for developers to be able to easily find and use APIs developed by other teams. Internal API discoverability fosters the reuse of existing functionality and reduces duplication of efforts across multiple teams.
• External developers: Public APIs are most commonly consumed by independent software developers or developers who work for other organizations. These developers benefit from API discoverability because they are looking for APIs that add specific features to their products.
• Partner developers: Some teams collaborate with developers at other organizations on specific API projects. These APIs should not be publicly available, but they should be available to the partner organization. Partner teams therefore need an elegant way to collaborate and discover one another’s API assets.

What are Postman workspaces?

Postman workspaces are collaborative spaces that enable API producers and consumers to work together seamlessly on API projects. They allow users to onboard new team members efficiently, develop APIs faster, create more secure APIs, and improve their overall API discoverability.

We can liken Postman workspaces to real-life workspaces. As in any workspace, workers have their workbench set up exactly how they want to work. Different tools are available for performing various tasks and collaborating seamlessly with other co-workers. Postman workspaces provide developers with all the tools they need to collaborate on APIs while staying organized.

There are several types of workspaces, so users can choose the one that makes the most sense for their project:

• Team workspaces: enable users to work together at the team, cross-team, or cross-department levels.
• Private workspaces: enable users to collaborate with a select group of invited team members in a private space.
• Partner Workspaces: enable users to collaborate efficiently with external partners and stakeholders.
• Public workspaces: enable teams to make their API artifacts publicly available to external developers.

Related: Solving problems together with Postman workspaces

How do Postman workspaces make your APIs more discoverable?

Organizations can leverage Postman workspaces to improve the discoverability of their APIs in several ways:

Streamlined API collaboration in a centralized, well-organized space

Postman workspaces provide a centralized place where teams can collaborate on APIs throughout the API lifecycle. Workspaces can contain multiple collections, monitors, tests, pieces of documentation, and more. These assets are highly organized in workspaces, which enables team members to easily discover relevant API artifacts—and start using them quickly.

In a Partner Workspace, for example, API partners can discover and access all of the API artifacts they need—such as documentation, tests, and workflow demos—with little external help.

Reduced time to first call (TTFC)

The time to first call (TTFC) is one of the most important API metrics. The amount of time it takes for developers to get fully set up and make a first successful request is crucial to improving API adoption. A lower TTFC means developers get to value faster and spend less time figuring things out.

Postman workspaces provide a shared space for working on collections, which are organized groups of API requests. They often have everything a developer needs to run an API successfully, including request headers, bodies, authorization details, and more. Workspaces also include environments, which are groups of variables used within a workspace that can change depending on the context. Environments in workspaces can be shared with a team.

With collections and environments, sending the first successful request can be as simple as forking a collection and clicking the Run collection button (it might also be necessary to set up environment variables for public workspaces if the workspace has one). Developers spend significantly less time making their first API request when they fork a collection. In fact, they make a successful API call 1.7 to 56 times faster when using a forked collection. 

In this case study, Swapnil Sapar, a Principal Engineer at Paypal, mentioned how Postman helped Paypal reduce their time to first call from 60 minutes to one minute. They also shortened their testing time from hours to minutes with collections.

Improved visibility for public and private APIs

Workspaces can be made publicly available on Postman’s Public API Network, which enables teams to seamlessly share their APIs, collections, and Flows with API consumers. The Public API Network contains over 200,000 workspaces and 500,000 collections, and it allows external developers to discover APIs directly in Postman or on search engines.

Any developer can contribute to a public workspace by forking one of its collections, making changes, and then making a pull request to the original collection. The owner of the public workspace can then review this pull request and merge it if it looks good to them. Allowing API consumers to contribute directly to the API promotes further adoption of the API.

On the other hand, the Private API Network is a centralized hub where internal teams can discover and reuse one another’s APIs and API assets. Workspaces published to the Private API Network are easily searchable and accessible, which promotes internal API discoverability across teams.

Auto-generated documentation for collections

APIs that are well documented are more discoverable because they are easier to find, understand, and implement. Workspaces can host auto-generated collection documentation, which includes request headers, authorization details, query and path parameters, request bodies, and response examples for every request.

Users can also add descriptions for each API component to provide additional context, and they can auto-generate client-side code snippets in over ten programming languages.

Shareability

Workspaces—and most of the assets they contain—are shareable artifacts. Public workspaces can be shared externally with a URL. This promotes discoverability because the URL can be embedded and referenced in multiple places. Additionally, team, partner, and private workspaces can be shared with team members who have the appropriate roles and permissions.

Collections can also be shared with a “Run in Postman” button. This button can be embedded in API documentation, repo READMEs, and markdown files. It provides a nice entry point for forking and running a collection as quickly as possible.

Search optimization

Public workspaces are visible to search engines and are optimized to rank highly. Published collection documentation is also optimized for SEO to ensure it reaches the right audience. This further strengthens API discoverability by ensuring API consumers can easily find the APIs they’re looking for—and start working with them quickly.

Related: How to publish and market your API to maximize adoption

Don’t forget to register here to attend POST/CON 24, Postman’s biggest API conference ever: April 30 to May 1, 2024 in San Francisco.