How Companies Are Exposing Their API Design Assets Internally

It’s well known that APIs drive much of the software built within the enterprise; a company should aim to efficiently use its own services.

For that reason, API discovery is important for engineers consuming those APIs. APIs in development can benefit from internal knowledge sharing, and searching API design assets can encourage consistency and avoid duplication.

API descriptions, such as the industry-driven OpenAPI format, enable machine-readable definitions of services. However, additional tools are needed to expose the design assets within these descriptions. Many organizations use OpenAPI to generate documentation in API portals. While this helps with service discovery, it also does get granular enough to help API designers.

In this post, we’ll look at what’s missing from current approaches, and dig into how repositories of design assets can begin to help organizations with their API design management.

OpenAPI Does Not Solve Discovery

We’re obviously big supporters of OpenAPI. Our tools work with OpenAPI 2.0, OpenAPI 3.0, and now the latest version, OpenAPI 3.1. And Stoplight is a member of the OpenAPI Initiative, so we see the importance of the industry-wide adoption of API descriptions. However, API discovery goes beyond a single format.

You want to have a complete view of the API design assets in your company. OpenAPI documents expose your endpoints and models in a machine-readable format. But the next step of aggregating multiple descriptions and searching within requires additional effort. Even if your thousands of APIs and microservices are documented, it doesn’t mean you can easily find them.

OpenAPI is only one type of design asset. There are JSON schemas, other description formats, and Markdown documentation to consider, as well. None of these assets themselves are meant to aid discovery, so companies look for other solutions to the problem.

API Portals Focus on Service Discovery

Developers building with public APIs use portals to access credentials and documentation. When we looked at how experts organize 1000s of APIs, we learned many companies use internal portals to help employees discover what’s available. However, portals focus on API consumer use cases. Teams building new APIs have no way to discover API design assets, only services.

A typical portal organizes individual APIs or groups of services. Essentially, it acts as a directory, possibly organized by type or business unit. If search is supported, it’s likely restricted to the services name and possibly a description.

When searching during the API design phase, you might want to look for:

• Models
• Fields
• Endpoints
• Hosts

While these are often present within documentation, engineers have to dig to find the asset needed by another API. Even the best portal documentation can only enable copy-and-paste design assets. For example, if an API designer uses an existing model, future changes to that model will not be shared between APIs.

Most API portals operate beyond these design details, and for good reason. They are built to enable service discovery. By keeping the focus on API consumption, they miss the mark for an engineer with questions answered by design assets.

Meta-Repos Collect Design Assets in One Place

A promising trend among enterprises is to use one or more code repositories to store design assets. Identifying the various descriptions (and related files) is the first step to discovery. You can write scripts to analyze them. And when anything is updated, your version control system can automatically send notifications to the appropriate parties.

These “meta-repos,” which contain OpenAPI and other documents, still aren’t easily searchable on their own. However, they are an improvement over portals, because they do more easily expose the more granular design assets. You may be able to find all the schema files for models. Depending on the search capabilities of your version control, you may even be able to see which OpenAPI documents reference specific models.

Most likely, you’ll write code to analyze your design assets. You’ll wire together scripts to re-run when the meta-repos update. When you have APIs described in a machine-readable way, it allows for connecting various tools together. Just as you can generate tests or documentation, you can also expose your design assets internally.

API Design Management Enables Better Governance

Complete API discovery within the enterprise must support both consumer and designer use cases. You want engineers and others to find the right APIs to use. As important, you want to build upon assets you already have. Inconsistency and duplication can slow all your teams down. Proper API governance requires you to have a view of all your API programs.

Your approach to API design management directly impacts the full API lifecycle. When API designers can find existing models and example styles, they will build more consistent interfaces. Further, through active design management, you can encourage consistency. Tools like Spectral allow for custom rulesets, which you can run automatically with each change to OpenAPI descriptions.

Meta-repos to store API design assets enable a workflow that helps you discover inconsistency and duplication. Stoplight Studio can read and write design assets to any Git repo. It has built-in linting with Spectral to help you enable consistency. This is the beginning of our efforts to help customers with their API design management.

We believe that you’ll build better APIs when API design assets are available throughout the API lifecycle. Engineers will integrate more easily, but also they’ll have the information to design thoughtful APIs from the start. You may be less likely to deprecate APIs, as duplication becomes less of a concern.