backend-api

DataFlow WebUI Backend (FastAPI)

⚠ CHANGE POLICY: Before creating any new endpoint, service, or registry, check webui-change-policy.mdc. Only operator rendering support and existing-resource CRUD fixes are allowed. New analytical endpoints, dashboards, and feature-level APIs are prohibited unless the user explicitly overrides.

Response Envelope — ALL responses return HTTP 200

This project wraps every response in ApiResponse[T]. Errors are NOT HTTP 4xx/5xx on the wire — they are success: false with the real status in meta.http_status.

from app.api.v1.resp import ok, created, no_content
from app.api.v1.envelope import ApiResponse

# Success
return ok(data)                    # {"success": true, "code": 200, "data": ...}
return created(data)               # Same shape, HTTP still 200
return no_content()                # Empty body, HTTP 200

# Errors — raise HTTPException or ApiError subclass, handler wraps into ApiResponse
from fastapi import HTTPException
raise HTTPException(404, "Pipeline not found")  # → {"success": false, "code": 40400, ...}

from app.api.v1.errors import NotFoundError, ConflictError, ValidationBizError
raise NotFoundError("Dataset not found")        # code=40401, meta.http_status=404

Endpoint Pattern

from fastapi import APIRouter, HTTPException
from app.api.v1.envelope import ApiResponse
from app.api.v1.resp import ok, created
from app.core.container import container
from app.schemas.my_resource import MyResourceIn, MyResourceOut

router = APIRouter(tags=["my_resource"])

# GET list
@router.get("/", response_model=ApiResponse[list[MyResourceOut]],
            operation_id="list_my_resources", summary="列出所有资源")
def list_my_resources():
    return ok(container.my_resource_registry.list())

# POST create
@router.post("/", response_model=ApiResponse[MyResourceOut],
             operation_id="create_my_resource", summary="创建新资源")
def create_my_resource(payload: MyResourceIn):
    try:
        result = container.my_resource_registry.add_or_update(payload.model_dump(mode="json"))
    except Exception as e:
        raise HTTPException(400, f"Failed to create: {e}")
    return created(result)

# GET by id
@router.get("/{resource_id}", response_model=ApiResponse[MyResourceOut],
            operation_id="get_my_resource", summary="获取单个资源")
def get_my_resource(resource_id: str):
    item = container.my_resource_registry.get(resource_id)
    if not item:
        raise HTTPException(404, "Resource not found")
    return ok(item)

# PUT update
@router.put("/{resource_id}", response_model=ApiResponse[MyResourceOut],
            operation_id="update_my_resource", summary="更新资源")
def update_my_resource(resource_id: str, payload: MyResourceUpdateIn):
    data = payload.model_dump(exclude_unset=True)
    updated = container.my_resource_registry.update(resource_id, data)
    return ok(updated)

# DELETE
@router.delete("/{resource_id}", response_model=ApiResponse[dict],
               operation_id="delete_my_resource", summary="删除资源")
def delete_my_resource(resource_id: str):
    item = container.my_resource_registry.get(resource_id)
    if not item:
        raise HTTPException(404, "Resource not found")
    container.my_resource_registry.remove(resource_id)
    return ok(message="Resource deleted")