# REST API First Migration Plan

Migrate NexusCRM frontend from SOQL queries to Salesforce REST API first principles.

## Principle

> **SOQL is LAST RESORT only.** Use Salesforce REST API endpoints first.

---

## Survey Summary

| Category | File | SOQL Queries | REST Alternative? |
|----------|------|--------------|-------------------|
| **Folders** | `metadata.ts:686` | `SELECT...FROM Folder` | ✅ `/folders` API |
| **AppMenu** | `metadata.ts:389` | `SELECT...FROM AppMenuItem` | ✅ `/appMenu/AppSwitcher` |
| **Organization** | `metadata.ts:815` | `SELECT...FROM Organization` | ✅ `/sobjects/Organization/{Id}` |
| **Approvals** | `approvals.ts` | ProcessInstanceWorkitem (3x) | ✅ `/process/approvals` |
| **Flows** | `flows.ts`, `ApiEndpoints.ts` | FlowDefinition (4x) | ⚠️ Tooling API (no REST alt) |
| **Permissions** | `ApiEndpoints.ts` | ObjectPermissions, FieldPermissions | ⚠️ No REST (SOQL required) |
| **Data Query** | `data.ts` | buildSOQL() generic | ✅ `/sobjects/{object}/{id}` for single, `/composite` for batch |
| **Audit Logs** | `useAuditLogs.ts` | History objects | ⚠️ No REST (SOQL required) |

---

## Proposed Changes

### 1. Folders API (`metadata.ts`)

**Current (SOQL)**:
```typescript
SELECT Id, Name, DeveloperName, Type, AccessType FROM Folder WHERE Type = '${type}'
```

**Change to REST**: `/services/data/v63.0/folders`

> [!IMPORTANT]
> The Folders REST API supports listing but no filtering by type. Need to filter client-side OR accept this as SOQL case.

---

### 2. AppMenuItem (`metadata.ts`)

**Current (SOQL)**:
```typescript
SELECT Id, Label, Description, StartUrl, Type FROM AppMenuItem WHERE IsVisible = true
```

**Change to REST**: `/services/data/v63.0/appMenu/AppSwitcher`

---

### 3. Organization (`metadata.ts`)

**Current (SOQL)**:
```typescript
SELECT Id, Name, PrimaryContact, Division, Address FROM Organization
```

**Change to REST**: `/services/data/v63.0/sobjects/Organization/{orgId}`

---

### 4. Process Approvals (`approvals.ts`)

**Current (SOQL)**:
```typescript
SELECT...FROM ProcessInstanceWorkitem ORDER BY CreatedDate DESC
```

**Change to REST**: `/services/data/v63.0/process/approvals/`

> [!NOTE]
> Salesforce Process Approvals REST API provides pending approvals, approve/reject actions.

---

### 5. Single Record Queries (`data.ts`)

**Current (SOQL)**:
```typescript
buildSOQL() → SELECT...FROM {object} WHERE Id = '{id}'
```

**Change to REST**: `/services/data/v63.0/sobjects/{ObjectName}/{Id}`

---

### 6. Record Lists (`data.ts`)

**Current (SOQL)**:
```typescript
buildSOQL() → SELECT...FROM {object} WHERE...ORDER BY...LIMIT
```

**Options**:
- `/sobjects/{object}/listviews/{listViewId}/results` for list views
- `/composite/sobjects` for batch operations
- **SOQL ACCEPTABLE** for complex filtering (last resort)

---

## Exceptions (SOQL Acceptable)

These have **no REST alternative**:

| Usage | Reason |
|-------|--------|
| FlowDefinition/FlowInterview | Tooling API only, no REST endpoints |
| ObjectPermissions/FieldPermissions | No REST API for permission queries |
| History objects (Audit) | No REST API for field history |
| Complex WHERE clauses | Generic filtering requires SOQL |
| Aggregate queries (COUNT, SUM, GROUP BY) | No REST alternative |

---

## Task Breakdown

### Phase 1: High-Value Migrations (REST Available)

- [ ] **T1.1**: Migrate AppMenuItem to `/appMenu/AppSwitcher`
- [ ] **T1.2**: Migrate Organization to `/sobjects/Organization/{Id}`  
- [ ] **T1.3**: Migrate Approvals pending to `/process/approvals`
- [ ] **T1.4**: Add single-record REST path in `dataAPI.getRecord()`

### Phase 2: Evaluate Folders API

- [ ] **T2.1**: Research if `/folders` REST endpoint supports type filtering
- [ ] **T2.2**: If yes, migrate; if no, document as SOQL exception

### Phase 3: Document Exceptions

- [ ] **T3.1**: Create `SOQL_EXCEPTIONS.md` documenting justified SOQL usages
- [ ] **T3.2**: Add inline comments to all remaining SOQL explaining why no REST alt

---

## Verification Plan

### Automated
```bash
# TypeScript compilation
npx tsc --noEmit

# Grep for remaining SOQL - should only be documented exceptions
grep -r "SELECT.*FROM" frontend/src --include="*.ts" | wc -l
```

### Manual (Browser)
1. Navigate to `/dashboards` → Verify folders load
2. Navigate to `/approvals` → Verify pending approvals show
3. Navigate to `/setup/profiles` → Verify profile list loads
4. Open App Switcher → Verify apps load

---

## Success Criteria

- [ ] All SOQL usages with REST alternatives are migrated
- [ ] Remaining SOQL usages are documented with justification
- [ ] All pages function correctly in browser
- [ ] TypeScript compiles without errors