Build a versioned capability-discovered HTTP API #58

New issue

Open

opened 2026-07-26 02:34:42 +00:00 by lost-rob0t · 2 comments

lost-rob0t commented

2026-07-26 02:34:42 +00:00

(Migrated from github.com)

Goal

Turn the current Ningle routes into a versioned StarIntel service contract that Quasar and other clients can discover instead of hard-coding legacy behavior.

Scope

add /api/v1/capabilities with schema revisions, supported transports, endpoints, limits, auth modes, queue/view features, and server build metadata
move or alias existing document, search, dataset, and target routes under /api/v1
define a stable JSON envelope and structured error format
return correct HTTP status codes and content types
add configurable CORS for browser clients, including preflight handling
add token/service-account authentication hooks without embedding credentials in URLs
publish an OpenAPI document generated or verified in CI
retain documented compatibility aliases for existing /new/*, /targets/*, /search, and view routes during migration

Acceptance criteria

Quasar can connect, authenticate, and feature-detect from one request
unsupported features are explicit rather than inferred from 404s
legacy routes have compatibility tests
OpenAPI and implementation contract tests run in CI
secrets are never returned by capability or diagnostic endpoints

This is the foundation for the expanded Quasar ↔ starintel-server adapter; the current HTTP API is the compatibility seed, not the final design.

## Goal Turn the current Ningle routes into a versioned StarIntel service contract that Quasar and other clients can discover instead of hard-coding legacy behavior. ## Scope - add `/api/v1/capabilities` with schema revisions, supported transports, endpoints, limits, auth modes, queue/view features, and server build metadata - move or alias existing document, search, dataset, and target routes under `/api/v1` - define a stable JSON envelope and structured error format - return correct HTTP status codes and content types - add configurable CORS for browser clients, including preflight handling - add token/service-account authentication hooks without embedding credentials in URLs - publish an OpenAPI document generated or verified in CI - retain documented compatibility aliases for existing `/new/*`, `/targets/*`, `/search`, and view routes during migration ## Acceptance criteria - Quasar can connect, authenticate, and feature-detect from one request - unsupported features are explicit rather than inferred from 404s - legacy routes have compatibility tests - OpenAPI and implementation contract tests run in CI - secrets are never returned by capability or diagnostic endpoints This is the foundation for the expanded Quasar ↔ starintel-server adapter; the current HTTP API is the compatibility seed, not the final design.

lost-rob0t commented

2026-07-27 00:05:46 +00:00

(Migrated from github.com)

Okay, some requirements:

Add a configuration symbol to disallow the legacy API. It should default to true.
Keep the routes similar to the existing routes, but place them under the versioned path.
These requirements may require additional issues and PRs.

Okay, some requirements: * Add a configuration symbol to disallow the legacy API. It should default to `true`. * Keep the routes similar to the existing routes, but place them under the versioned path. * These requirements may require additional issues and PRs.

lost-rob0t commented

2026-08-24 06:51:01 +00:00

(Migrated from github.com)

RAGE implementation slice #109 / PR #110 is now carrying the public/private API split for this overhaul: versioned unauthenticated read-only search + aggregate stats for public clients/watch use, while ingest/targets remain authenticated and capability-authorized. Exact-head CI is being used as the merge gate.