Managed SDK Workflows

Managing SDK generation in the enterprise isn't just about code generation - it's about understanding how deeply personal engineering workflows have become.

Think about your code editor preferences. Your git workflow. Your project structure. These aren't just technical choices - they're extensions of how your mind works. Some of us organize in hierarchies, others in flat structures. Some version through tags, others through branches. Each choice feels natural, obvious, even right to us.

When we started rebuilding Sideko's SDK workflow system, we discovered this human truth everywhere we looked. The API team that kept their OpenAPI spec in a pristine monorepo wasn't just following a technical best practice - they were expressing their need for order and consistency. The platform team generating specs from code annotations wasn't just being pragmatic - they were showing their belief that truth lives in the implementation. And the UI team with specs scattered across repositories? They were prioritizing their autonomy and flexibility.

We had stumbled into something deeper than a technical problem. This wasn't about making teams change their workflows - it was about honoring how teams naturally organize their world.

That's when we shifted our thinking from "How do we standardize API workflows"? to "How do we embrace workflow diversity"?

The answer came in the form of a simple configuration that lets teams express their preferences. The configuration can be expressed as a .yaml file or in OpenAPI x-fields.

Copied!
api: my-api
servers:
  - url: https://api.special.dev/v1
    name: production
    default: true
languages:
  rust:
    sdk_name: special_client_rs
    cli: true
    auths:
      - id: ApiKeyAuth
        param: api_key
modules:
  - path: special.project.utils
    operations:
      - id: createApiProject
        function_name: create

This system lets teams keep their Git branches or their semantic versions, their monorepos or their distributed specs, their auto-generated or hand-crafted documentation. It acknowledges that there isn't one right way to manage APIs, just as there isn't one right way to organize your desk or structure your day.

Importantly, SDK ownership differs across organizations and APIs. Sometimes there is a central developer experience (DevEx) team that wants to own the SDKs and work hard on optimizing the module system for readability. In this case, DevEx can create and maintain the configuration in a git repository that they own. Othertimes, it's a busy engineering team that wants a typescript SDK that simply gets the job done. In this case, they can simply tell Sideko they want Typescript, and start using the SDK immediately.

At the end of the day, the best workflow system isn't the one that enforces uniformity - it's the one that makes space for our human need to do things our own way.

Differences in Versioning, Tooling, and Team Structure

Every organization we work with has their own unique way of handling APIs. Some maintain a single pristine OpenAPI spec. Others have specs scattered across multiple repositories. Still others dynamically generate specs from code annotations.

But that was just the beginning of the complexity:

• Teams managed versioning through Git tags, separate branches, or dedicated version directories
• Some needed internal SDKs with privileged operations while maintaining public SDKs
• Some teams prefer to use x-fields in OpenAPI, while others want to keep their specifications clean and simple

The challenge wasn't just technical - it was organizational. We needed to build a system flexible enough to accommodate these diverse workflows while remaining simple enough to be immediately useful.

Config Tooling

We utilize the Sideko CLI to help DevEx teams get started with the Sideko config. sideko sdk config init my-api -> Creates a configuration with all defaults applied. To support our DevRel teams, we will continue to build out tooling to make it even easier to customize the config without editing the file by hand.

Beyond Code Generation

The workflow system doesn't just generate code - it maintains it. Teams can:

1. Make manual modifications to generated code that persist across regeneration
2. Version SDKs independently from API versions
3. Use release-candidate versions of SDKs internally before releasing

Engineering Required to Support These Flows

Building workflows for SDK development presented a fascinating challenge - creating a stateless system that could handle inherently stateful processes. The breakthrough came from recognizing that we needed to be surgeons, not demolition crews.

When teams modify generated SDKs - adding optimizations, custom methods, or specialized logic - they're creating valuable intellectual property. Traditional code generation would obliterate these improvements with each update. Instead, we built an tree-based system that performs precise code surgery. By parsing both existing and new code into abstract syntax trees, we can identify exactly what changed in the API specification and apply those changes with surgical precision, preserving the surrounding tissue of custom code.

But understanding code structure was only half the battle. We needed to grapple with versioning - both of the APIs and the SDKs themselves. This led us to build a filesystem abstraction layer that could parse Git history and understand versioning patterns for SDKs, and a seperate API for OpenAPI management, versioning, and linting.

The end result is a stateless system that enables natural, stateful workflows. Teams can develop their SDKs organically while maintaining consistency with the underlying APIs. It's like having an expert developer who knows exactly what changed, what to preserve, and how to evolve the codebase forward Sometimes the best automation isn't about replacing human workflows, but about understanding and enhancing them.