Why build yet another API Client?

by Jeremy Jay

Two years ago, I was working on a large greenfield development project. The scope was ambitious: multiple frontend and backend teams, customer-specific job tracking systems, and numerous vendor integrations. Early on, we recognized that APIs would be the backbone of our system, so we adopted OpenAPI document to manage it all.

The OpenAPI Specification is powerful, covering a broad range of API-related concerns. For teams like ours using typed languages, JSON Schemas within OpenAPI provide even more value by ensuring our systems could communicate seamlessly. Yet, despite the widespread adoption of JSON Schema and OpenAPI, I was baffled that our API tool, Postman, could not use our JSON Schemas for contract testing or even simple request validation. Our developers had to write custom tests just to verify that requests and responses conformed to the schemas, meaning our ability to deliver and maintain robust integrations was severely restricted.

Honestly this was the kicker that helped me decide to build an new API client, with some core tenets that separate it from the rest. The first tenet is that JSON Schema is a first-class feature.

JSON Schema as a First-Class Feature

Callosum doesn’t just validate JSON Schemas; it helps developers create them from scratch. The app includes intelligent schema suggestions that analyze your API requests and responses to infer a schema directly from the content. Your engineers don’t need to refer to RFCs, or annotate their code in a specific way for this to work. Working from the response itself accelerates the development process by reducing all that manual effort and ensuring that your schemas are both accurate and comprehensive against the latest implementation. With JSON Schema as a cornerstone, Callosum makes it easier to build APIs that are reliable and consistent across all integrations.

{
  "userId": 1,
  "id": 4,
  "title": "eum et est occaecati",
  "body": "ullam et saepe reiciendis
  voluptatem adipisci sit amet autem
  assumenda provident rerum culpa quis
  hic commodi nesciunt rem tenetur
  doloremque ipsam iure quis sunt
  voluptatem rerum illo velit"
}

{
  "properties": {
    "body": {
      "type": "string"
    },
    "id": {
      "type": "number"
    },
    "title": {
      "type": "string"
    },
    "userId": {
      "type": "number"
    }
  },
  "type": "object"
}

Proprietary Collections begone!

Working on a large team, another pain point easily emerges: keeping our OpenAPI documents in sync with the API collections in Postman is nearly impossible. Too often, these Postman collections diverge from the source of truth, creating friction for developers and other stakeholders since there is no easy way to tell what is accurate. I realized that instead of relying on all the competing standards and derived collections for sharing APIs with our teams, we should fully embrace the extensibility of OpenAPI itself. That’s why Callosum only uses OpenAPI documents—all API information is stored directly within the OpenAPI document using portable and well-documented extensions.

This approach isn’t just about reducing friction for developers. It also empowers cross-functional teams—developers, technical writers, and product managers—to collaborate more effectively. Because there’s no conversion between formats, collaboration is smoother, and changes can be easily compared in version control. Callosum makes it easier than ever to keep your documentation, design, and implementation environments in sync.

A Commitment to Privacy

As I was building these core features, a shift in the API tooling ecosystem really shook me and my colleages. Multiple API clients (Postman, Insomnia) began restricting features behind a required cloud-connected account. While I understand the appeal of cloud sync and online collaboration, I’ve always valued privacy and my ability to disconnect from distractions and work offline. This inspired Callosum’s third core tenet: privacy-preserving access to advanced features and an offline-first approach to development. I’ll probably build toward cloud sync eventually, but not at the expense of happy users.

Callosum ensures that developers have access to powerful tools without compromising privacy or relying on constant connectivity. This focus allows teams to work securely and quickly, even in constrained environments.

Looking Ahead

Callosum has already streamlined API development for me in significant ways, but this is just the beginning. I’m really excited about what’s coming in 2025. The recently introduced OpenAPI Overlay specification unlocks new opportunities to mix dynamically generated OpenAPI documents, with detailed documentation, and implementation and usage details. New features like automated contract testing, better collaboration tools, and CI/CD integration are in the works for Callosum, and I think they’ll be significant multipliers to how our teams build and maintain APIs.

Callosum solves some of the frustrations many engineers face when working with APIs. Give it a shot to see if it works for you and your team!