# API V1 Admin vs Legacy Implementation Comparison

## Overview
This document compares the V1 API admin implementations with the legacy API implementations to identify deviations and ensure adequate information is returned for the React app.

---

## 1. GET /admin

### V1 Implementation
- Returns: `GetAdmin200JSONResponse` with `DatabaseInfo`
- DatabaseInfo contains: `documentsSize`, `activitySize`, `progressSize`, `devicesSize`
- Gets documents count from `GetDocumentsSize(nil)`
- Aggregates activity/progress/devices across all users using `GetDatabaseInfo`

### Legacy Implementation
- Function: `appGetAdmin`
- Returns: HTML template page
- No direct database info returned in endpoint
- Template uses base template variables

### Deviations
**None** - V1 provides more detailed information which is beneficial for React app

### React App Requirements
✅ **Sufficient** - V1 returns all database statistics needed for admin dashboard

---

## 2. POST /admin (Admin Actions)

### V1 Implementation
- Actions: `BACKUP`, `RESTORE`, `CACHE_TABLES`, `METADATA_MATCH`
- Returns: `PostAdminAction200ApplicationoctetStreamResponse` with Body as io.Reader
- BACKUP: Streams ZIP file via pipe
- RESTORE: Returns success message as stream
- CACHE_TABLES: Returns confirmation message as stream
- METADATA_MATCH: Returns not implemented message as stream

### Legacy Implementation
- Function: `appPerformAdminAction`
- Actions: Same as V1
- BACKUP: Streams ZIP with proper Content-Disposition header
- RESTORE: After restore, redirects to `/login`
- CACHE_TABLES: Runs async, returns to admin page
- METADATA_MATCH: TODO (not implemented)

### Deviations
1. **RESTORE Response**: V1 returns success message, legacy redirects to login
   - **Impact**: React app won't be redirected, but will get success confirmation
   - **Recommendation**: Consider adding redirect URL in response for React to handle

2. **CACHE_TABLES Response**: V1 returns stream, legacy returns to admin page
   - **Impact**: Different response format but both provide confirmation
   - **Recommendation**: Acceptable for REST API

3. **METADATA_MATCH Response**: Both not implemented
   - **Impact**: None

### React App Requirements
✅ **Sufficient** - V1 returns confirmation messages for all actions
⚠️ **Consideration**: RESTORE doesn't redirect - React app will need to handle auth state

---

## 3. GET /admin/users

### V1 Implementation
- Returns: `GetUsers200JSONResponse` with array of `User` objects
- User object fields: `Id`, `Admin`, `CreatedAt`
- Data from: `s.db.Queries.GetUsers(ctx)`

### Legacy Implementation
- Function: `appGetAdminUsers`
- Returns: HTML template with user data
- Template variables available: `.Data` contains all user fields
- User fields from DB: `ID`, `Pass`, `AuthHash`, `Admin`, `Timezone`, `CreatedAt`
- Template only uses: `$user.ID`, `$user.Admin`, `$user.CreatedAt`

### Deviations
**None** - V1 returns exactly the fields used by the legacy template

### React App Requirements
✅ **Sufficient** - All fields used by legacy admin users page are included

---

## 4. POST /admin/users (User CRUD)

### V1 Implementation
- Operations: `CREATE`, `UPDATE`, `DELETE`
- Returns: `UpdateUser200JSONResponse` with updated users list
- Validation:
  - User cannot be empty
  - Password required for CREATE
  - Something to update for UPDATE
  - Last admin protection for DELETE and UPDATE
- Same business logic as legacy

### Legacy Implementation
- Function: `appUpdateAdminUsers`
- Operations: Same as V1
- Returns: HTML template with updated user list
- Same validation and business logic

### Deviations
**None** - V1 mirrors legacy business logic exactly

### React App Requirements
✅ **Sufficient** - V1 returns updated users list after operation

---

## 5. GET /admin/import

### V1 Implementation
- Parameters: `directory` (optional), `select` (optional)
- Returns: `GetImportDirectory200JSONResponse`
- Response fields: `CurrentPath`, `Items` (array of `DirectoryItem`)
- DirectoryItem fields: `Name`, `Path`
- Default path: `s.cfg.DataPath` if no directory specified
- If `select` parameter set, returns empty items with selected path

### Legacy Implementation
- Function: `appGetAdminImport`
- Parameters: Same as V1
- Returns: HTML template
- Template variables: `.CurrentPath`, `.Data` (array of directory names)
- Same default path logic

### Deviations
1. **DirectoryItem structure**: V1 includes `Path` field, legacy only uses names
   - **Impact**: V1 provides more information (beneficial for React)
   - **Recommendation**: Acceptable improvement

### React App Requirements
✅ **Sufficient** - V1 provides all information plus additional path data

---

## 6. POST /admin/import

### V1 Implementation
- Parameters: `directory`, `type` (DIRECT or COPY)
- Returns: `PostImport200JSONResponse` with `ImportResult` array
- ImportResult fields: `Id`, `Name`, `Path`, `Status`, `Error`
- Status values: `SUCCESS`, `EXISTS`, `FAILED`
- Same transaction and error handling as legacy
- Results sorted by status priority

### Legacy Implementation
- Function: `appPerformAdminImport`
- Parameters: Same as V1
- Returns: HTML template with results (redirects to import-results page)
- Result fields: `ID`, `Name`, `Path`, `Status`, `Error`
- Same status values and priority

### Deviations
**None** - V1 mirrors legacy exactly

### React App Requirements
✅ **Sufficient** - All import result information included

---

## 7. GET /admin/import-results

### V1 Implementation
- Returns: `GetImportResults200JSONResponse` with empty `ImportResult` array
- Note: Results returned immediately after import in POST /admin/import
- Legacy behavior: Results displayed on separate page after POST

### Legacy Implementation
- No separate endpoint
- Results shown on `page/admin-import-results` template after POST redirect

### Deviations
1. **Endpoint Purpose**: Legacy doesn't have this endpoint
   - **Impact**: V1 endpoint returns empty results
   - **Recommendation**: Consider storing results in session/memory for retrieval
   - **Alternative**: React app can cache results from POST response

### React App Requirements
⚠️ **Limited** - Endpoint returns empty, React app should cache POST results
💡 **Suggestion**: Enhance to store/retrieve results from session or memory

---

## 8. GET /admin/logs

### V1 Implementation
- Parameters: `filter` (optional)
- Returns: `GetLogs200JSONResponse` with `Logs` and `Filter`
- Log lines: Pretty-printed JSON with indentation
- Supports JQ filters for complex filtering
- Supports basic string filters (quoted)
- Filters only pretty JSON lines

### Legacy Implementation
- Function: `appGetAdminLogs`
- Parameters: Same as V1
- Returns: HTML template with filtered logs
- Same JQ and basic filter logic
- Template variables: `.Data` (log lines), `.Filter`

### Deviations
**None** - V1 mirrors legacy exactly

### React App Requirements
✅ **Sufficient** - All log information and filtering capabilities included

---

## Summary of Deviations

### Critical (Requires Action)
None identified

### Important (Consideration)
1. **RESTORE redirect**: Legacy redirects to login after restore, V1 doesn't
   - **Impact**: React app won't automatically redirect
   - **Recommendation**: Add `redirect_url` field to response or document expected behavior

2. **Import-results endpoint**: Returns empty results
   - **Impact**: Cannot retrieve previous import results
   - **Recommendation**: Store results in session/memory or cache on client side

### Minor (Acceptable Differences)
1. **DirectoryItem includes Path**: V1 includes path field
   - **Impact**: Additional information available
   - **Recommendation**: Acceptable improvement

2. **Response formats**: V1 returns JSON, legacy returns HTML
   - **Impact**: Expected for REST API migration
   - **Recommendation**: Acceptable

### No Deviations
- GET /admin (actually provides MORE info)
- GET /admin/users
- POST /admin/users
- POST /admin/import
- GET /admin/logs

---

## Database Access Compliance

✅ **All database access uses existing SQLC queries**
- `GetDocumentsSize` - Document count
- `GetUsers` - User list
- `GetDatabaseInfo` - Per-user stats
- `CreateUser` - User creation
- `UpdateUser` - User updates
- `DeleteUser` - User deletion
- `GetUser` - Single user retrieval
- `GetDocument` - Document lookup
- `UpsertDocument` - Document upsert
- `CacheTempTables` - Table caching
- `Reload` - Database reload

❌ **No ad-hoc SQL queries used**

---

## Business Logic Compliance

✅ **All critical business logic mirrors legacy**
- User validation (empty user, password requirements)
- Last admin protection
- Transaction handling for imports
- Backup/restore validation and flow
- Auth hash rotation after restore
- Log filtering with JQ support

---

## Recommendations for React App

1. **Handle restore redirect**: After successful restore, redirect to login page
2. **Cache import results**: Store POST import results for display
3. **Leverage additional data**: Use `Path` field in DirectoryItem for better UX
4. **Error handling**: All error responses follow consistent pattern with message

---

## Conclusion

The V1 API admin implementations successfully mirror the legacy implementations with:
- ✅ All required data fields for React app
- ✅ Same business logic and validation
- ✅ Proper use of existing SQLC queries
- ✅ No critical deviations

Minor improvements and acceptable RESTful patterns:
- Additional data fields (DirectoryItem.Path)
- RESTful JSON responses instead of HTML
- Confirmation messages for async operations

**Status**: Ready for React app integration