OpsLevel Logo
Product
Developer portal
Software catalog
Understand your entire architecture at a glance
Standards
Your guide to safe, reliable software
Developer self-service
Empower developers to move faster, risk-free
Integrations
Connect your most powerful third-party tools
Use Cases
Ownership
Build accountability and clarity into your catalog
Standardization
Set and rollout best practices for your software
Developer Experience
Free up your team to focus on high-impact work
Customers
Resources
All Resources
Our full library of resources
Pricing
Flexible and designed for your unique needs
Podcast
Podcast
Conversations with technical leaders
Blog
Blog
DevOps resources, tips, and best practices
Demo
Demo
Videos of our product and features
Tech talk
Tech talk
Our POV on technical topics
Guide
Guide
Practical resources to roll out new programs and features
DocsLog In
Talk to usTry for free
No items found.
Share this
Table of contents
 
Resources
Blog

Introducing API Docs from OpsLevel

Product
Documentation
Visibility
DevX
Developer
Platform engineer
Introducing API Docs from OpsLevel
OpsLevel
|
August 1, 2022
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.

Configure a service to use either the pull or push method for API Docs.
 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.

Each service in OpsLevel now has an API Docs tab.

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.

For each endpoint and request type developers can review the details of parameters and responses.

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.

More resources

Blog
September 19, 2023
by
Fernando Villalba
The OpsLevel Developer Experience (DevEx) series. Part 1: What is DevEx?

Great developer experience (DevEx) is what you get when developers can easily achieve and maintain flow state at work. This article begins a series where we tackle all of the areas that affect flow state and impair your developer experience at your company and provide example metrics and suggestion to help you operate like a potential future unicorn.

Blog
August 31, 2023
by
OpsLevel
August 2023 release notes

This month included an update to our Service Maturity features—to give you even more flexibility—plus more sorting and syncing improvements. Read on to learn more!

Blog
May 31, 2023
by
Haley Hnatiw
May 2023 release notes

See what we’ve shipped in the month of May.

OpsLevel Logo
Subscribe
Join our newsletter to stay up to date on features and releases.
By subscribing you agree to with our Privacy Policy and provide consent to receive updates from our company.
SOC 2AICPA SOC
Product
Software CatalogMaturityIntegrationsSelf-serviceRequest a demo
Company
About usCareersContact UsCustomersPartnersSecurity
Resources
Docs
Blog
Demo
© 1999 J/K Labs Inc. All rights reserved.
Cookie Preferences
Terms of Use
Privacy Policy
Responsible Disclosure
By using this website, you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View our Data Processing Agreement for more information.
Okay!