Extending OpenAPI instead of reinventing the wheel (again)

The landscape of API tools is full of applications that each define their own way of managing and sharing API information. Postman collections, Insomnia collections, Bruno’s Bru markup language, Hoppscotch collections, and other proprietary formats abound, creating a fragmented ecosystem. While these tools each offer some convenience in their own ecosystem, they force teams into siloed workflows and make it challenging to maintain a single source of truth.

With Callosum, I wanted to take a different approach: instead of introducing yet another data-sharing format, Callosum builds on the extensibility of OpenAPI through well-documented extensions, a strategy increasingly adopted by other modern OpenAPI tools such as Speakeasy and Redocly.

Breaking Free from Proprietary Formats

Proprietary formats allow tool developers to build new functionality quickly within specific ecosystems, but severely limit collaboration and scalability for API teams. For example, a team might use OpenAPI for serverless deployments, but also maintain a separate Postman collection for testing and sharing – resulting in duplicated effort and a risk of outdated or mismatched data. Similarly, a backend team using Insomnia might struggle to align with a product team writing Redocly documentation in OpenAPI for public distribution, as their workflows rely on different, incompatible file formats. These silos forced by the tools make it harder for developers, product managers, and technical writers to collaborate effectively. OpenAPI extensions offer a solution by centralizing the API information in a flexible and tool-agnostic way.

How Callosum Harnesses OpenAPI Extensions

Callosum uses OpenAPI extensions to manage the developer and user experience for an API. Features such as environments (variables and groups, security configurations, and encrypted variable storage), request and response optimization (parameter templates and automatic variable extraction), and sharing mechanisms (deeplink ID generation) are embedded directly within the OpenAPI document. This ensures:

Portability: The OpenAPI standard defines that unknown extensions should be ignored and passed through, so the Callosum extensions will never conflict with other OpenAPI tools.
Streamlined Workflows: The need to manually sync data or convert between tools is no longer necessary, as all information is contained within the same file and intended for reuse by other tools.
Flexibility for the Future: As OpenAPI evolves or API patterns change, extensions can still adapt to meet any new requirements. Since proprietary formats are not usually intended for use in custom pipelines, they will be brittle and difficult to support long-term.

By adopting OpenAPI extensions, Callosum aligns with the broader trend of open standards in software development. Open standards encourage interoperability between tools, foster innovation, and empower teams to choose workflows that suit their unique needs.

Building a More Collaborative OpenAPI Ecosystem

The API ecosystem doesn’t need more isolated tools or exclusive formats. Callosum extensions promote an open and collaborative development environment. Teams can maintain a single source of truth, adapt quickly to changing needs, and focus on delivering high-quality APIs.

Are you ready to simplify your API development workflows? Give Callosum a try!