# Operations-Focused Routers

Routers primarily serving observatory automation with critical operations buffering.

```{contents} Table of Contents
:depth: 2
:local: true
```

## Executed Obs Units Router

**Path**: `/executed_obs_units`

**Purpose**: Record actual telescope observations

**Key endpoints**:

- `POST /start` - Start observation (buffered)
- `PUT /{id}/finish` - Finish observation (buffered)
- `GET /{obs_unit_id}` - Query observations (smart query)

**Example from code**:

```{literalinclude} ../../../ccat_ops_db_api/routers/executed_obs_units.py
:emphasize-lines: 1-5, 20-25
:language: python
:lines: 40-90
```

**Characteristics**:

- `@critical_operation` decorator
- Pre-generated UUIDs
- Smart queries merge buffer + database
- High reliability requirement

## Raw Data Files Router

**Path**: `/raw_data_files`

**Purpose**: Register data files produced by instruments

**Key endpoints**:

- `POST /` - Register file (buffered)
- `POST /bulk` - Register multiple files (buffered)
- `GET /{id}` - Get file metadata

**Example**:

```python
@router.post("/bulk")
@critical_operation
async def register_files_bulk(
    files: List[RawDataFileCreate],
    _transaction_builder = Depends(get_transaction_builder)
):
    # Bulk create step
    files_step = _transaction_builder.bulk_create(
        model_class=models.RawDataFile,
        data_list=[f.dict() for f in files],
        step_id="bulk_create_files"
    )

    return {"count": len(files), "status": "buffered"}
```

## Raw Data Package Router

**Path**: `/raw_data_package`

**Purpose**: Group related data files

**Key endpoints**:

- `POST /` - Create package (buffered)
- `GET /{id}` - Get package with files
- `PUT /{id}/finalize` - Mark complete

**Characteristics**:

- Groups files by observation
- Size limits (50GB max recommended)
- Status tracking (building → complete)

## Staging Router

**Path**: `/staging`

**Purpose**: Data staging for transfer

**Key endpoints**:

- `POST /stage` - Request staging (buffered)
- `GET /status/{id}` - Check status
- `DELETE /{id}` - Cancel staging

## Next Steps

- {doc}`shared-routers` - Shared routers
- {doc}`../../tutorials/observatory-integration/recording-observations` - Using in scripts