Skip to content
Soxom

Quick Start

This guide takes you from a fresh Soxom account to a published SDK release. The end state: a tagged version of your SDK in a Production Repository, ready to install from your package registry of choice.

Prerequisites

Section titled “Prerequisites”
  • Signed up and connected GitHub.
  • A rough idea of the API you want to model. You can start from Soxom’s template if you don’t have an OpenAPI spec yet.

1. Create a project

Section titled “1. Create a project”
  1. From the Soxom dashboard, click New Project and give it a name (e.g. petstore).
  2. Pick the GitHub account or org where the Config Repository should live.
  3. Click Create.

Soxom creates a new GitHub repository — your Config Repository — pre-populated with a starter openapi.yaml and soxom.yaml. The dashboard links to the repo as soon as it’s ready.

2. Add an SDK target

Section titled “2. Add an SDK target”
  1. Open the project in the dashboard and go to SDK Targets.
  2. Click Add Target and pick a language. Start with TypeScript or Python — Java is also supported, and Go is in preview.
  3. Choose the package name (@myorg/petstore or petstore-sdk) and confirm.

For each target, Soxom creates two managed repositories under the same GitHub account: a Staging Repository (where generated code lives during development) and a Production Repository (where tagged releases are cut).

3. Define your API

Section titled “3. Define your API”

Clone your Config Repository locally and edit the two files Soxom created.

  1. Replace the starter openapi.yaml with your real API definition. A minimal example:

    openapi.yaml
    openapi: 3.1.0
    info:
      title: Pet Store API
      version: 1.0.0
    servers:
      - url: https://api.petstore.example.com/v1
    security:
      - bearerAuth: []
    paths:
      /pets:
        get:
          operationId: listPets
          responses:
            "200":
              description: A list of pets
              content:
                application/json:
                  schema:
                    type: object
                    properties:
                      data:
                        type: array
                        items: { $ref: "#/components/schemas/Pet" }
                      has_more: { type: boolean }
        post:
          operationId: createPet
          requestBody:
            required: true
            content:
              application/json:
                schema: { $ref: "#/components/schemas/PetCreate" }
          responses:
            "201":
              description: Pet created
              content:
                application/json:
                  schema: { $ref: "#/components/schemas/Pet" }
      /pets/{pet_id}:
        get:
          operationId: getPet
          parameters:
            - { name: pet_id, in: path, required: true, schema: { type: string } }
          responses:
            "200":
              description: Pet details
              content:
                application/json:
                  schema: { $ref: "#/components/schemas/Pet" }
    components:
      securitySchemes:
        bearerAuth: { type: http, scheme: bearer }
      schemas:
        Pet:
          type: object
          required: [id, name, species]
          properties:
            id: { type: string }
            name: { type: string }
            species: { type: string, enum: [dog, cat, bird] }
        PetCreate:
          type: object
          required: [name, species]
          properties:
            name: { type: string }
            species: { type: string, enum: [dog, cat, bird] }

  2. Update soxom.yaml with your SDK metadata and target packages:

    soxom.yaml
    version: "1.0"
    

    sdk:
      name: petstore-sdk
      version: 1.0.0
      description: SDK for the Pet Store API
    

    spec:
      path: ./openapi.yaml
    

    targets:
      typescript:
        package_name: "@petstore/sdk"
        module_format: esm
      python:
        package_name: petstore_sdk
        min_version: "3.9"

    See the soxom.yaml reference for the full schema (pagination, retries, auth, streaming, resources, and so on).

  3. Commit and push to main.

4. Watch the build

Section titled “4. Watch the build”

The push fires a webhook to Soxom. Open the Builds page in the dashboard to watch:

  • The Config Repository commit being picked up.
  • The appropriate generator(s) running for each enabled SDK target.
  • Generated code being committed to codegen/next in each Staging Repository.
  • Custom code (if any) being merged on extended/next and then onto next.

A successful build ends with Soxom opening (or updating) a staging-release PR in each Staging Repository.

5. Merge the staging release

Section titled “5. Merge the staging release”

Open the staging-release PR Soxom created. It contains the diff against the previous staging release, the changelog Soxom assembled, and the proposed version bump. Review it like any other PR — request changes, ask for review, run any tests you’ve added to the Staging Repository — then merge.

Merging the staging PR triggers the next step automatically.

6. Cut a production release

Section titled “6. Cut a production release”

Soxom opens a production-release PR in the Production Repository, taking the just-merged staging code and preparing it for publication. Merging this PR:

  • Creates a git tag (e.g. v1.1.0) on the Production Repository.
  • Optionally publishes the package to your chosen registry (npm, PyPI, Maven Central) if you’ve configured publishing credentials.

That’s a full release. From here on, every push to your Config Repository flows through the same pipeline.

Next steps

Section titled “Next steps”