Standards

This document defines the foundational standards for all k0rdent APIs: request/response structure, naming conventions, field design, and operational patterns across Atlas, Arc, and shared services.

Table of Contents

• API Response Contract
• Field Design Rules
• Implementation Reference
• Naming Conventions
• Action Endpoints
• Bulk Operations
• Workflow Operations
• Error Handling
• Audit Logging
• Multi-Tenancy Patterns

---

API Response Contract

All API responses use a consistent discriminated union envelope structure with a success boolean discriminator.

Type Definition

Base Meta Object

The meta object is always present and contains request tracking information:

Extension Meta Types

Success responses can extend meta with additional context:

Error Response Structure

Response Examples

Meta Object Design Decisions

---

Implementation Reference

Technology Stack

Zod Schema Definitions

Define all request/response schemas using Zod for validation and type inference:

---

Field Design Rules

Design fields for extension from day one. The cost of refactoring primitive fields into objects later is high and often requires breaking changes.

Use Objects Over Primitives

Wrap values that might grow into objects immediately.

Never Use Booleans for State

States often grow beyond two values.

Use IDs with Optional Expansion

Don't embed full objects. Use IDs and let clients request expansion.

---

API Versioning

All API endpoints include version in the URL path: /v1/...

Domain-based routing separates Atlas and Arc APIs:

Version Format

Version Policy

• Major versions (v1, v2) for breaking changes
• No minor versions in URL - use feature flags and deprecation warnings instead
• Deprecation timeline: 6 months notice before removing deprecated endpoints
• Version in URL, not response: The apiVersion field is omitted from responses because the URL path is the source of truth

Deprecation Example

---

Naming Conventions

Consistent naming across URLs, fields, and resources improves developer experience and reduces confusion.

URL Paths

Hono uses colon-prefixed route parameters.

Resource IDs

Resources (clusters, servers, organizations, etc.) get globally unique, opaque IDs that do NOT contain region information. This decouples resource identity from physical location.

Format: {prefix}_{base62}

Special ID: org_system is reserved for platform-level admin operations. TBD if this is needed still. Originally it was for something else.

Field Names

---

Pagination

Use cursor-based pagination for real-time data, offset/limit for stable datasets.

Query Parameters

Response

---

Filtering and Sorting

Query String Format

Use consistent query parameter patterns for filtering and sorting:

Implementation with Zod

---

Action Endpoints

For operations beyond CRUD, use a unified action endpoint with POST method. Actions represent commands that change resource state asynchronously.

Design Principles

1. Unified Endpoint: Single /actions endpoint handles all action types (power, provision, deprovision, inspect, maintenance)
2. Type-Safe Parameters: Each action type has its own request schema with action-specific options
3. Async by Default: Actions return 202 Accepted with workflow/operation IDs for tracking
4. Audit Trail: Logs show "POST /actions with type=power action=off" for clear tracking
5. Granular Permissions: Easy to scope permissions like servers:lifecycle vs servers:update

Endpoint Pattern

Action Request Schema

Implementation Example

---

Bulk Operations

Bulk operations allow applying actions to multiple resources simultaneously. All bulk actions use partial success semantics - individual resource failures do not fail the entire bulk operation.

Design Principles

1. Partial Success: Individual failures don't abort the entire bulk operation
2. Explicit IDs: Use explicit ID lists for predictability and safety
3. Per-Resource Results: Response includes success/failure status for each resource
4. 207 Multi-Status: Always return 207 to indicate mixed results possible
5. Dedicated Endpoints: Use /bulk pattern for consistency

Endpoint Pattern

The action type is specified in the request body, making the API flexible and maintainable.

Request Schema

Response Structure

Implementation Example

Safety Features

Dry-Run Mode

Preview which resources would be affected without executing:

Response:

Rate Limiting

Bulk operations are throttled to prevent resource overload. Default: 10 requests/min.

---

Workflow Operations

Long-running operations that interact with infrastructure (BMC, Kubernetes) return 202 Accepted immediately with a workflow ID for tracking. All infrastructure mutations flow through durable workflows.

Design Principles

1. Immediate Response: Return 202 within < 1 second, don't wait for completion
2. Workflow ID: Provide workflow run ID for polling or webhook correlation
3. Estimated Duration: Give clients a hint for progress UI
4. Status Endpoint: Query workflow status via /v1/workflows/runs/:id
5. Webhook Integration: Support webhooks for completion notifications

Workflow Orchestration

Use a durable workflow engine for retryable task execution:

Workflow Status Endpoint

Client Integration Pattern

---

Implementation Reference

---

Error Handling

Typed Error Classes

Define semantic error types for consistent error responses:

Global Error Handler

Usage in Routes

---

Audit Logging

SOC 2 compliant audit logging for all API requests. Every significant action must be traceable to a user and timestamp.

What to Log

Sensitive Entities Requiring Audit Logs

These entities require audit logging on all operations, including reads:

Audit Event Schema

Audit Event Naming Convention

Use past-tense, dot-namespaced actions:

---

Multi-Tenancy Patterns

Row-Level Security (RLS)

Use PostgreSQL RLS for defense-in-depth isolation:

Setting Context Per Request

---

Decision Log

Response Envelope Pattern

Resource ID Format

Action Endpoints

Bulk Operation Responses

Async Operation Default

---

Testing

Test Structure

All API endpoints should have integration tests covering:

1. Happy path: Successful requests with expected responses
2. Validation: Invalid inputs return appropriate errors
3. Authorization: Unauthorized users receive 403
4. State transitions: Invalid state transitions are rejected
5. Edge cases: Empty lists, missing resources, etc.

Test Helpers

Example Test

---

Related Documentation

• Specification - Complete API specification with detailed endpoint examples
• Auth Architecture - Authentication, authorization, and multi-tenant security patterns
• Data Ownership - Implementation patterns, workflow orchestration, and development guidance
• Data Model - Database schema and relationships