Skip to main content

api.common

Shared helpers for request validation and response composition in the exp HTTP layer.

The module keeps endpoint implementations thin by centralizing:

  • query validation for target and config-name inputs,
  • standardized JSON error responses,
  • typed response assembly for build-time, run-time, and single-config payloads,
  • cache-header decisions for runtime-derived responses.

ErrorDetails Objects​

class ErrorDetails(TypedDict)

Optional error metadata returned alongside the top-level error message.

TargetResolution Objects​

@dataclass(frozen=True, slots=True)
class TargetResolution()

Represents a validated target query plus its resolved configuration index.

ConfigNameResolution Objects​

@dataclass(frozen=True, slots=True)
class ConfigNameResolution()

Represents a validated config-name query plus its registered metadata.

json_response​

def json_response(body: dict[str, object],
                  status_code: int = 200) -> JSONResponse

Create a JSON response with the provided payload and status code.

utcnow_iso​

def utcnow_iso() -> str

Return the current UTC time as an ISO 8601 string.

error_response​

def error_response(message: str,
                   status_code: int,
                   details: ErrorDetails | None = None) -> JSONResponse

Build a consistent JSON error response.

resolve_target_query​

def resolve_target_query(
    raw_value: str, *, parameter_name: str
) -> tuple[TargetResolution | None, JSONResponse | None]

Validate and resolve a target query parameter to a known target index.

resolve_config_name_query​

def resolve_config_name_query(
    raw_value: str, *, parameter_name: str
) -> tuple[ConfigNameResolution | None, JSONResponse | None]

Validate and resolve a config-name query parameter to a known config definition.

build_missing_keys_error​

def build_missing_keys_error(document_name: str,
                             missing_required_keys: list[str]) -> JSONResponse

Build a 500 response for a target document with missing required keys.

build_missing_config_value_error​

def build_missing_config_value_error(config_name: str) -> JSONResponse

Build a 500 response for a required config key that is absent from the store.

build_internal_resolution_error​

def build_internal_resolution_error(context: str) -> JSONResponse

Build a 500 response for an unexpected empty query-resolution result.

build_build_time_response​

def build_build_time_response(
    *, resolution: TargetResolution, config: dict[str, str]
) -> ApiBuildTimeConfigDocumentResponse | WebsiteBuildTimeConfigDocumentResponse

Build the typed build-time response payload for a resolved target.

build_run_time_response​

def build_run_time_response(
    *, resolution: TargetResolution, config: dict[str,
                                                  str], features: dict[str,
                                                                       bool]
) -> ApiRunTimeConfigDocumentResponse | WebsiteRunTimeConfigDocumentResponse

Build the typed run-time response payload for a resolved target.

build_config_value_response​

def build_config_value_response(
        *, resolution: ConfigNameResolution, value: str,
        refresh_interval_seconds: int) -> ConfigValueResponse

Build the typed single-config response payload for a resolved config name.

is_non_cacheable_path​

def is_non_cacheable_path(path: str) -> bool

Return whether a request path serves runtime-derived configuration data.

resolve_caller_label​

def resolve_caller_label(request: Request, resolved_target: str) -> str

Return a stable caller label for process-local diagnostics.

Azure callers expose a principal ID header via Easy Auth. Local or proxy callers do not have a principal identity, so the resolved consumer target is used instead.

// was this page useful?