Generating client SDKs from the OpenAPI spec

Pulp Engine maintains first-class clients for:

Language	Package	Hand-written or generated?
TypeScript	@pulp-engine/sdk	Hand-written
Python	pulp-engine	Hand-written
Java, Go, .NET, Ruby, PHP, Kotlin, Swift, Rust, …	Not shipped as a first-class package. Operators generate on demand from openapi.json — see § Generating a client with openapi-generator.	User-generated

Availability: the TypeScript and Python SDKs are hand-maintained and live in the (private) source repository (packages/sdk-typescript/ and packages/sdk-python/). They are not yet published to npm or PyPI — registry publication is pending trusted-publisher setup; do not npm install @pulp-engine/sdk / pip install pulp-engine until the packages are live. Until then: licence holders with a source arrangement can consume the in-repo packages directly; evaluators without source access should generate a client from openapi.json (next section) — the spec ships with every release and is served live at /docs/json. All other languages are user-generated from openapi.json either way.

For languages outside the supported set — Java, Go, .NET, Ruby, PHP, Kotlin, Swift, Rust, etc. — you can auto-generate a client yourself from the OpenAPI 3.0.3 specification at openapi.json (repo root). The spec is regenerated from the live Fastify server via pnpm extract-openapi and CI verifies it stays fresh on every PR via pnpm extract-openapi --check.

Where to find the spec

Source	Location
Repo file (always current)	openapi.json
Live API (when DOCS_ENABLED=true)	GET /docs/json
Swagger UI (when DOCS_ENABLED=true)	GET /docs

Production note: DOCS_ENABLED defaults to false in production Docker images. To download the spec from a running server, either run a development instance or fetch the file from the repo.

Generating a client with openapi-generator

openapi-generator supports 50+ languages. Install it via:

# npm (no JRE required for the CLI wrapper)
npm install -g @openapitools/openapi-generator-cli

# Or via Docker
docker pull openapitools/openapi-generator-cli

Java

openapi-generator-cli generate \
  -i openapi.json \
  -g java \
  -o ./sdk-java \
  --additional-properties=library=native,groupId=com.pulp-engine,artifactId=pulp-engine-sdk

Go

openapi-generator-cli generate \
  -i openapi.json \
  -g go \
  -o ./my-go-client \
  --git-user-id=yourorg \
  --git-repo-id=yourrepo \
  --additional-properties=packageName=pulpengine

Note: Go package identifiers reject hyphens, so package pulp-engine is a syntax error. Use pulpengine or any other valid Go identifier. The generator’s moduleName additional property is ignored — the module line is always github.com/{gitUserId}/{gitRepoId}; post-process go.mod if you need a different module path.

C# / .NET

openapi-generator-cli generate \
  -i openapi.json \
  -g csharp \
  -o ./my-dotnet-client \
  --additional-properties=targetFramework=net8.0,packageName=YourCompany.PulpEngineClient,library=httpclient

Other languages

See the openapi-generator generators list for Ruby, PHP, Kotlin, Swift, Rust, etc.

Authentication

Pulp Engine supports two authentication schemes (both defined in the spec):

Scheme	Header	When to use
ApiKeyAuth	X-Api-Key: dk_admin_...	Server-to-server integrations
EditorTokenAuth	X-Editor-Token: ...	Short-lived editor session tokens (8h TTL)

Configure your generated client to send the appropriate header on every request. Most generators expose this via a Configuration or RequestInterceptor API.

Reference implementations

When in doubt about resource shape, error handling, or pagination, look at the two hand-crafted SDKs:

• TypeScript: packages/sdk-typescript/src/ — resource classes, error mapping, pagination helper
• Python: packages/sdk-python/pulp_engine/ — same surface area, snake_case, Pydantic models

Both follow the same resource layout (templates, render, batch, assets, etc.) so the API contract is unambiguous.

Reporting SDK issues

If a generated client misbehaves, the issue is usually one of:

1. The OpenAPI spec is incomplete or wrong — file an issue against Pulp Engine with the failing endpoint and the generator output
2. The generator has a bug — file with openapi-generator
3. Auth headers aren’t being sent — check your generator’s auth configuration

For language-specific tuning (idiomatic naming, async support, etc.), the polished TypeScript and Python SDKs are good models for what to add on top of the generated baseline.