Introducing API Docs from OpsLevel

For software developers working on complex distributed architectures, navigating boundaries is a recurring task. Depending on how narrowly their teams and services are scoped, much, or even most, of their work requires interacting with services they don’t own.

Whether they’re asking another service for data of some kind or trying to ensure they respond as expected to requests from internal customers (i.e. other services), there’s a consistent need to be aware of and communicate across boundaries.

That’s why internal API Docs are an essential resource for any high-performing engineering org using microservices.

Without API Docs integrated into a comprehensive service catalog, developers waste time:

 
• searching in multiple places for docs
 
• building against outdated specs
 
• debugging and reworking
 
• recreating the wheel

Adding API Docs to OpsLevel’s Developer Portal

OpsLevel aims to make low-level, recurring tasks–like finding and using internal API documentation–lower friction for developers. For API Docs, this means making it easier for:

 
• service owners to populate their docs into OpsLevel
 
• developers to consume them
 
• platform teams to drive and track adoption of docs standards

Our new API Docs capability checks all these boxes. Let’s review how it works.

Populating API docs in OpsLevel

The most straightforward way to ingest endpoint documentation is to let OpsLevel pull swagger.json files from your services’ git repositories. This makes things very easy for service owners; if a service has a linked repository, OpsLevel will check for and import API docs. Learn more about the pull method for API docs, including how to change what repo directory OpsLevel pulls from, in our docs.

But we know that in large organizations, different teams and services have different constraints and follow different patterns or workflows in their development lifecycles. So if the pull method doesn’t work for your use case, you can also push your API docs to OpsLevel.

With the push method, your can docs come from anywhere as long as you send them to us in an OpenAPI (.yaml or .json ) format. Check out the details here. Importantly, you’re able to mix and match; some services can use the pull method while others use push.

 Today API Docs supports only REST APIs in the OpenAPI Specification. Support for other specifications is planned.

Consuming API Docs in OpsLevel

In OpsLevel, each service detail screen now has a dedicated tab for API Docs. OpsLevel uses a custom implementation of Swagger UI to render endpoint information.

Organized by endpoint, each request type includes standard details about the input parameters allowed, responses, and sample payloads. Clicking on any request will update the URL in the address bar, creating a deep link that can be shared with teammates.

Integrating API Docs with Service Ownership

To provide the largest benefit to developers, it’s best that API docs are consolidated in one central place. This mandate may flow “top down”, but like most work in distributed architectures, it’s more efficient if completed by the service owners who have the most context.

So we’re also adding a Has API Docs check to help engineering leaders bring clear visibility and accountability to endpoint documentation. With this check, orgs can ensure every service with an internal API has corresponding docs in OpsLevel.

The new check type can be used in either (or both) the Service Maturity Rubric or our dedicated Campaigns.

With Campaigns, you can launch, message, and track the rollout of an API docs initiative to ensure all stakeholders are aware of the importance of the project. Using the rubric, you can make internal API documentation a routine activity for service owners and continuously verify that docs are populated in OpsLevel.

Get Started with API Docs Today

Ready to try out OpsLevel’s API Docs in your organization? Request your OpsLevel demo today.