browser/openspec/changes/implement-platform-api-surface/specs/platform-api-surface/spec.md

ADDED Requirements

Requirement: Core resource HTTP routes are implemented

The platform SHALL expose HTTP JSON routes for create, list, and detail workflows for users, AI providers, game management plugins, server instances, run endpoints, jobs, artifacts, log streams, and audit events.

Scenario: Resource is created through API

• WHEN a valid create request is posted to a core resource collection route
• THEN the platform MUST persist the resource through service.Core and return 201 with the corresponding named response DTO

Scenario: Resource list is requested

• WHEN a client sends GET to a core resource collection route
• THEN the platform MUST return 200 with a named list response DTO containing resources from service.Core

Scenario: Resource detail is requested

• WHEN a client sends GET to a core resource detail route with an existing resource ID
• THEN the platform MUST return 200 with the corresponding named response DTO

Requirement: API handlers use centralized DTO and service contracts

The platform SHALL keep API request, response, list, and error contracts in platform/dto and SHALL call service.Core for resource workflows.

Scenario: Handler decodes request body

• WHEN an API handler accepts a request body
• THEN it MUST decode into a named DTO type from platform/dto and convert that DTO to a named domain type before calling service.Core

Scenario: Handler returns response body

• WHEN an API handler returns a success or error response
• THEN it MUST encode a named DTO response type and MUST NOT define response structs inside handler functions

Requirement: API errors are stable JSON responses

The platform SHALL return named JSON error DTOs for malformed requests, validation failures, duplicate resources, missing resources, unsupported methods, and unexpected failures.

Scenario: Invalid JSON is submitted

• WHEN a client posts malformed JSON to a core resource route
• THEN the platform MUST return 400 with a JSON error response

Scenario: Validation fails

• WHEN a create request violates validator or service invariants
• THEN the platform MUST return 400 with a JSON error response and MUST NOT persist the resource

Scenario: Duplicate resource is submitted

• WHEN a create request uses an ID that already exists
• THEN the platform MUST return 409 with a JSON error response

Scenario: Missing resource is requested

• WHEN a client requests a resource ID that does not exist
• THEN the platform MUST return 404 with a JSON error response

Requirement: AI provider API preserves credential redaction

The AI provider API SHALL return redacted provider response DTOs that include secret references only and never raw API keys.

Scenario: AI provider is created through API

• WHEN a valid AI provider create request is posted
• THEN the platform MUST return an AIProviderResponse containing apiKeyRef and MUST NOT include raw API key fields

Scenario: Raw AI key is submitted as key reference

• WHEN an AI provider create request includes raw key material in apiKeyRef
• THEN the platform MUST reject the request with 400 and MUST NOT persist the provider

Requirement: Router is injectable and local-development ready

The platform SHALL provide router construction that accepts a core service for tests and future persistence, and a default router that uses the in-memory core service for local development.

Scenario: Local platform process starts

• WHEN cmd/platform creates the default router
• THEN the router MUST expose /healthz and all implemented core API routes backed by an in-memory service.Core

Scenario: Tests provide a service

• WHEN tests call router construction with an explicit service.Core
• THEN handlers MUST use that service instance for all route operations

Requirement: Route catalog matches implemented API surface

The platform route catalog SHALL identify implemented core API routes and clearly distinguish deferred run transport, log ingest, artifact chunk, plugin bridge, and AI invocation behavior.

Scenario: Contributor inspects API catalog

• WHEN a contributor opens platform/api/routes.md
• THEN the file MUST list the implemented create, list, and detail routes and MUST identify deferred behavior as not implemented by this change

Requirement: API handler tests verify surface behavior

The platform SHALL include API tests covering successful create/list/detail workflows, JSON error mapping, dependency validation, duplicate handling, missing resources, and AI provider redaction.

Scenario: Platform API tests run

• WHEN go test ./... is executed inside platform/
• THEN tests MUST verify the implemented HTTP API behavior without external services or a database