distributor/docs/roadmap/api.md

API Roadmap

This document records API work that is not part of the current implementation. Current HTTP upload behavior is documented in docs/integrations/http-upload.md, current configuration behavior is documented in docs/config.md, and current producer package usage is documented under docs/consumers/.

Implemented HTTP Upload Behavior

The pipeline-scoped HTTP upload API is implemented. The current contract is:

• upload authentication is configured with top-level upload_tokens;
• token values resolve through the process environment or secrets.directory, never YAML literals;
• bearer tokens authenticate producers and authorize configured upload pipelines through allow_pipelines;
• upload requests use POST /v1/pipelines/{pipeline_id}/upload;
• missing, malformed, or unknown bearer tokens return 401 Unauthorized;
• valid tokens that are not allowed for the requested pipeline return 403 Forbidden;
• pkg/upload upload options require PipelineID;
• idempotency records are scoped by token id, pipeline id, and idempotency key;
• source manifests remain free of routing, destination, transform, and credential data.

The unscoped upload route no longer accepts uploads. Pipeline query parameters are rejected.

Deferred API Work

The following topics remain separate roadmap items:

• durable upload status storage;
• durable idempotency records across server restarts;
• in-app public exposure policy;
• built-in TLS termination;
• built-in upload rate limiting.

Boundaries

• Do not add destination selection to producer manifests.
• Do not let producers specify destination ids, transforms, links, publish policy, or transfer policy through the upload API.
• Keep http_upload source-only. A selected pipeline owns destination configuration, transforms, links, transfer policy, and publication behavior.