Calimero Core Server OpenAPI Specifications

January 23, 2026 · View on GitHub

This repository hosts OpenAPI specifications for Calimero Network services. It is used by CI checks in other repositories to detect breaking changes in API contracts.

📖 New to using OpenAPI specs? See CLIENT_USAGE.md for detailed examples of how clients can use these specs.

🌐 View Interactive Documentation: GitHub Pages - Browse all API specifications with interactive visualizations.

Quick Start

For Clients (Consuming APIs)

# 1. Fetch the spec
curl -O https://raw.githubusercontent.com/calimero-network/core-server-open-api/main/specs/core-server/openapi.yaml

# 2. Generate client code (TypeScript example)
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o src/generated/client

# 3. Use the generated client
import { CalimeroNodeClient } from './generated/client';
const client = new CalimeroNodeClient({ baseURL: 'http://localhost:8080' });

See CLIENT_USAGE.md for complete examples in multiple languages.

For Server Implementations

# 1. Checkout specs as submodule
git submodule add git@github.com:calimero-network/core-server-open-api.git openapi-specs

# 2. Validate your implementation
npx @apidevtools/swagger-cli validate openapi-specs/specs/core-server/openapi.yaml

# 3. Check for breaking changes in CI
bash openapi-specs/scripts/check-breaking-changes.sh \
  openapi-specs/specs/core-server/openapi.yaml \
  your-spec.yaml

Repository Structure

.
├── specs/                    # OpenAPI specification files
│   ├── core-server/          # Core server API specs
│   │   └── openapi.yaml      # Main core server OpenAPI spec
│   └── registry/             # Registry API specs
│       └── api.yml           # Registry API OpenAPI spec
├── scripts/                  # Utility scripts
│   ├── check-breaking-changes.sh  # Breaking change detection script
│   └── generate-docs.mjs     # Generate GitHub Pages documentation
├── examples/                 # Example code
│   ├── typescript-client-example.ts
│   ├── python-client-example.py
│   └── ci-workflow-example.yml
├── .github/
│   └── workflows/
│       ├── ci.yml            # CI workflow for validation
│       ├── pages.yml         # GitHub Pages deployment workflow
│       └── example-usage.yml # Example for other repos
├── docs/                     # Generated documentation (gitignored, generated in CI)
│   ├── index.html            # Documentation index page
│   ├── core-server.html      # Core Server API visualization
│   └── registry.html         # Registry API visualization
├── CLIENT_USAGE.md          # Detailed client usage guide
├── CONTRIBUTING.md          # Contribution guidelines
├── QUICKSTART.md            # Quick start guide
└── README.md                # This file

Purpose

This repository serves as the source of truth for OpenAPI specifications across the Calimero Network ecosystem. Other repositories can:

  1. Reference these specs to ensure API compatibility
  2. Validate their implementations against these specs
  3. Detect breaking changes before merging PRs
  4. Generate client code in multiple languages
  5. Ensure type safety across the stack

Usage in Other Repositories

Adding CI Checks

Add a workflow step to your repository that validates against the specs in this repo:

- name: Check API Breaking Changes
  uses: actions/checkout@v4
  with:
    repository: calimero-network/core-server-open-api
    path: openapi-specs
    token: ${{ secrets.GITHUB_TOKEN }}

- name: Validate OpenAPI Spec
  run: |
    npx @apidevtools/swagger-cli validate openapi-specs/specs/core-server/openapi.yaml
    
- name: Check for Breaking Changes
  run: |
    # Replace with your actual spec path
    bash openapi-specs/scripts/check-breaking-changes.sh \
      openapi-specs/specs/core-server/openapi.yaml \
      ./your-api-spec.yaml  # TODO: Update this path

See examples/ci-workflow-example.yml for a complete workflow.

Using as a Git Submodule

git submodule add git@github.com:calimero-network/core-server-open-api.git openapi-specs

Then reference the specs in your CI:

- name: Check Breaking Changes
  run: |
    bash openapi-specs/scripts/check-breaking-changes.sh \
      openapi-specs/specs/core-server/openapi.yaml \
      ./your-spec.yaml

Breaking Change Detection

The scripts/check-breaking-changes.sh script helps detect breaking changes by comparing specs:

  • Removed endpoints
  • Removed request/response fields
  • Changed field types
  • Changed required fields
  • Removed response codes

Running Locally

# Install dependencies
npm install

# Check breaking changes
bash scripts/check-breaking-changes.sh \
  specs/core-server/openapi.yaml \
  /path/to/new/spec.yaml

Contributing

Adding a New Spec

  1. Add your OpenAPI spec to specs/<service-name>/
  2. Ensure it follows OpenAPI 3.0+ format
  3. Validate it using npx @apidevtools/swagger-cli validate
  4. Update scripts/generate-docs.mjs to include your new spec in the specs array
  5. Update this README if needed
  6. Documentation will be automatically generated and published to GitHub Pages on merge

Updating Existing Specs

  1. Make your changes to the spec file
  2. Run validation: npm run validate
  3. Check for breaking changes: npm run check-breaking-changes
  4. Submit a PR with clear description of changes

Versioning

  • Use semantic versioning in the info.version field
  • Breaking changes should increment the major version
  • Non-breaking changes increment minor or patch versions

CI Workflow

This repository has a CI workflow that:

  1. Validates all OpenAPI specs
  2. Checks for syntax errors
  3. Ensures specs are well-formed
  4. Runs on every push and PR

Tools Used

Interactive Documentation

All OpenAPI specifications are automatically published to GitHub Pages with interactive visualizations:

The documentation is automatically regenerated on every push to the main branch.

Local Preview

Generate and preview the documentation locally:

# Generate documentation
npm run docs:generate

# Preview locally
npm run docs:preview

Documentation

License

Same as the main Calimero Network repository.