[Feature Request] API versioning (/api/v1/) and REST best practices roadmap

[strausmann]

Summary

We are building stable integrations on top of Dockhand (MCP servers, Ansible modules, Terraform providers) and are running into a fundamental limitation: the API has no versioning, making it difficult to build consumers that can rely on stable contracts.

This issue complements #814 (OpenAPI/Swagger) and is related to #543 and #729 (API token auth). We believe these three together form the foundation for a first-class developer experience.

---

1. Problem: No API Versioning

• All 130+ endpoints live under /api/ without a version prefix
• Breaking changes affect all consumers immediately
• There is no deprecation mechanism for removed or changed endpoints
• Integrators cannot pin to a stable API version
• This is a blocker for building stable MCP servers, Ansible modules, and Terraform providers

---

2. Proposed Solution: Versioned API

• Introduce /api/v1/ prefix for all current endpoints
• Keep /api/ as an alias for the latest version (backward compatible, no migration needed immediately)
• Future breaking changes go to /api/v2/
• Deprecation headers on old versions (Sunset header, RFC 8594)
• Maintain a changelog for API versions

---

3. Additional REST Best Practices (suggestions, not demands)

These are common patterns that would significantly improve the developer experience. We offer them as suggestions — the team knows the codebase best.

a) Pagination on list endpoints

GET /api/v1/containers?page=1&per_page=50

Response headers: X-Total-Count, Link (rel=next/prev)

Currently all list endpoints return full result sets — this becomes problematic at scale.

b) Filtering and Sorting

GET /api/v1/containers?status=running&environment_id=7&sort=name

Reduces client-side processing and bandwidth significantly for large environments.

c) Rate-Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711234567
Retry-After: 30  (on 429 responses)

We experienced rate limiting in practice (during Hawser authentication flows) but it is currently undocumented. Exposing these headers would help integrators handle backoff correctly.

d) Consistent Error Responses

A standard error envelope across all endpoints:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "details": {}
}

Combined with consistent HTTP status code usage, this greatly simplifies error handling in consumers.

e) ETag / If-None-Match for Caching

Reduces unnecessary data transfer for polling consumers (e.g., monitoring agents that poll container status every N seconds).

---

4. Suggested Migration Path

Phase	Action	Breaking?
1	Add /api/v1/ as alias for all current /api/ routes	No
2	Generate OpenAPI spec from /api/v1/ routes (see #814)	No
3	New features only on /api/v1/ or later	No
4	Deprecate unversioned /api/ (long timeline, with Sunset headers)	Soft

---

5. Why This Matters

Re: #813 — We recently struggled to find the correct token endpoint because the API structure is undiscoverable without documentation. The endpoint existed, but we could not find it. Versioning + OpenAPI (#814) together solve this permanently by making the API self-describing.

Re: #543 and #729 — Community members have been requesting API token authentication for a long time. A versioned API is a natural prerequisite for stable token-based access, as token consumers need a stable contract.

Re: enterprise adoption — Versioned APIs are table stakes for production integrations. Organizations that want to build automation pipelines on top of Dockhand need the confidence that an update to Dockhand will not silently break their tooling.

---

6. We Offer to Help

We have already mapped all 130+ endpoints from the source code as part of our work on #814. Specifically:

• We can help draft the /api/v1/ aliasing approach if the team approves the direction
• Our existing endpoint map can bootstrap the OpenAPI spec
• We are happy to review PRs or provide test cases from our integration suite

We are not asking for a specific timeline — just opening the discussion and signaling that we are willing to contribute if the approach aligns with the project roadmap.

---

References

• [Feature Request] Auto-generated OpenAPI/Swagger documentation for the REST API #814 — OpenAPI/Swagger spec (our issue, open)
• feat: API endpoint for Edge-mode Hawser token regeneration #813 — Edge Token API (our issue, closed — endpoint existed but was undiscoverable)
• [Feature Request] API Token Generation and Usage #543 — API Token Generation (community, open)
• [Feature Request] APP API Key #729 — APP API Key (community, open)

[strausmann]

Update: Combining with #814 (OpenAPI)

We're proposing to combine versioning with the OpenAPI documentation effort (#814) into a single PR. The rationale:

1. OpenAPI spec should only document the versioned API (/api/v1/)
2. Introducing /api/v1/ and OpenAPI together gives a clean starting point
3. Legacy /api/ gets deprecation headers but remains functional

See the detailed proposal in #814.

Migration for existing integrations

Before:  curl -b cookie http://dockhand:3000/api/environments
After:   curl -b cookie http://dockhand:3000/api/v1/environments  (preferred)
         curl -b cookie http://dockhand:3000/api/environments     (still works, deprecated)

No breaking changes. The PR is in progress.

[strausmann]

Extended Proposal: Zod Schemas as Core of the v1 Migration

While working on PR #816 (static OpenAPI spec), we encountered a fundamental limitation: the spec has to be maintained manually alongside the actual route handlers. Any time an endpoint changes, both the implementation and the spec need to be updated separately — and there's no compile-time guarantee they stay in sync.

We'd like to propose an enhanced approach that solves this at the architecture level.

---

The Problem with a Static OpenAPI Spec (PR #816)

PR #816 works as a transitional solution — it documents the current API accurately and is a solid step forward. But long-term, a static openapi.ts creates a second source of truth that will inevitably drift from the real implementation. The only way to prevent drift is discipline, which doesn't scale.

---

The Proposal: Zod Schemas + zod-to-openapi

The /api/v1/ migration is a clean-break moment. We propose using it to introduce Zod schemas as the single source of truth for both runtime validation and API documentation.

The pipeline:

Drizzle Schema (DB)
    ↓ drizzle-zod
Zod Schemas (Validation + Types)
    ↓ @asteasolutions/zod-to-openapi
OpenAPI 3.0 Spec (auto-generated)
    ↓ swagger-ui-dist
Swagger UI (/api/v1/docs)

This means:

• Schemas are defined once
• Request bodies are validated at runtime (Zod)
• TypeScript types are inferred from the schema (no duplication)
• The OpenAPI spec is generated automatically — no manual updates needed
• drizzle-zod bridges the DB schema to Zod, keeping DB types and API types in sync

---

Architecture Example: A v1 Endpoint

// src/lib/server/openapi-registry.ts
import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
export const registry = new OpenAPIRegistry();

// src/routes/api/v1/environments/+server.ts
import { z } from 'zod';
import { registry } from '$lib/server/openapi-registry';

// Single source of truth for the Environment resource
const EnvironmentSchema = registry.register('Environment', z.object({
  id: z.number(),
  name: z.string(),
  host: z.string(),
  port: z.number().default(2376),
  connectionType: z.enum(['hawser-standard', 'hawser-edge', 'tcp', 'socket']),
  tlsVerify: z.boolean().default(true),
  createdAt: z.string().datetime(),
}));

const CreateEnvironmentSchema = registry.register('CreateEnvironment', z.object({
  name: z.string().min(1).max(100),
  host: z.string().optional(),
  port: z.number().int().min(1).max(65535).default(2376),
  connectionType: z.enum(['hawser-standard', 'hawser-edge', 'tcp', 'socket']),
}));

// Route handler with automatic validation
export const GET: RequestHandler = async ({ cookies }) => {
  // ... existing logic, return type inferred from EnvironmentSchema
};

export const POST: RequestHandler = async ({ request, cookies }) => {
  // Zod validates and parses — throws 400 automatically on invalid input
  const body = CreateEnvironmentSchema.parse(await request.json());
  // body is now fully typed: { name: string, port: number, connectionType: ... }
  // ... existing logic
};

// src/routes/api/v1/docs/+server.ts — auto-generated from registry
import { OpenApiGeneratorV3 } from '@asteasolutions/zod-to-openapi';
export const GET: RequestHandler = async () => {
  const generator = new OpenApiGeneratorV3(registry.definitions);
  const spec = generator.generateDocument({ openapi: '3.0.0', info: { title: 'Dockhand API', version: '1.0.0' } });
  return json(spec);
};

---

Migration Strategy: /api/ → /api/v1/

Phase	Action	Breaking?
1	/api/v1/ aliases for all current routes (as originally planned)	No
2	PR #816 serves as transitional OpenAPI spec	No
3	Introduce Zod schemas on core endpoints (Environments, Containers, Stacks)	No
4	Replace static spec with auto-generated spec as Zod coverage grows	No
5	All v1 endpoints covered → deprecate PR #816 static spec	No

Zod schemas can be introduced incrementally — there's no need to migrate all 130+ endpoints at once.

---

How This Benefits PR #817 (API Tokens)

PR #817 (API Token authentication, refs #543 and #729) benefits directly from Zod schemas:

const CreateTokenSchema = registry.register('CreateApiToken', z.object({
  name: z.string().min(1).max(100),
  expiresAt: z.string().datetime().optional(),
  scopes: z.array(z.enum(['read', 'write', 'admin'])).default(['read']),
}));

const ApiTokenSchema = registry.register('ApiToken', z.object({
  id: z.number(),
  name: z.string(),
  prefix: z.string(), // dh_...
  lastUsedAt: z.string().datetime().nullable(),
  expiresAt: z.string().datetime().nullable(),
  createdAt: z.string().datetime(),
  // Note: full token only returned on creation, never again
}));

The token endpoint gets runtime validation + OpenAPI documentation automatically from the same schema definition.

---

Required Dependencies

bun add zod @asteasolutions/zod-to-openapi drizzle-zod

All three are ESM-compatible and work with Bun. drizzle-zod is the official Drizzle ORM package for generating Zod schemas from Drizzle table definitions, keeping DB types and API types in sync without duplication.

---

Comparison: Current vs. Proposed Approach

Aspect	PR #816 (static spec)	Zod-to-OpenAPI (v1)
Spec maintenance	Manual	Automatic
Request validation	None	Zod runtime check
TypeScript type safety	Spec only (no enforcement)	Types inferred from schema
Schema drift	Possible	Structurally impossible
DB schema sync	Manual	drizzle-zod bridge
Error responses	Manual	Zod validation errors, parseable
Incremental adoption	N/A	Yes, endpoint by endpoint

---

Our Offer

1. PR feat: Add OpenAPI/Swagger documentation for REST API #816 stays as the transitional spec — it's mergeable today and immediately useful
2. We can open a follow-up PR that migrates 5–10 core endpoints (Environments, basic Containers, Auth) to Zod as a PoC — showing the pattern without requiring a full rewrite
3. The two approaches are fully compatible: PR feat: Add OpenAPI/Swagger documentation for REST API #816 documents what exists now, Zod-generated spec replaces it incrementally as v1 matures

We're not asking for a full architecture decision upfront. The PoC PR would demonstrate whether the approach fits the codebase, and the team can decide how far to take it.

Happy to discuss further — refs #814, #816, #817.