---
name: step-04-api-smoke
description: Start the API and test CRUD endpoints with real HTTP requests
prev_step: steps/step-03-integration-tests.md
---

# Step 4: API Smoke Test

## BLOCKING - All CRUD endpoints must respond correctly

See `references/api-smoke-tests.md` for complete startup, CRUD sequence, and error classification.

---

## Quick Procedure

### 1. Find the API project

```bash
ls src/*Api*/*.csproj 2>/dev/null || ls *Api*/*.csproj 2>/dev/null
```

### 2. Start API (see reference for crash detection)

```bash
dotnet run --project {ApiProject} --urls "http://localhost:5099" > /tmp/api-smoke-output.log 2>&1 &
API_PID=$!
```

### 3. CRUD Tests

```bash
# GET all (200)
# POST create (201)
# GET by ID (200)
# PUT update (200)
# DELETE (204)
# GET deleted (404) — verify deletion
```

See `references/api-smoke-tests.md` section "CRUD Test Sequence" for exact curl commands.

### 4. HTTP Error Handling

| Status | Cause | Fix |
|--------|-------|-----|
| 401 | Auth not configured | Check JWT setup |
| 403 | Permissions missing | Verify PermissionConfiguration |
| 404 | Route not registered | Check NavRoute on controller |
| 500 | Unhandled exception | Check API logs |
| Connection refused | API won't start | Check appsettings.json |

### 5. Crash Classification

If API crashes at startup:
- Classify error from `/tmp/api-smoke-output.log`
- See `references/api-smoke-tests.md` section "Crash Classification"
- Common: MISSING_PACKAGE, VERSION_MISMATCH, MISSING_DI, DATABASE_ERROR

### 6. Stop API

```bash
kill $API_PID 2>/dev/null
wait $API_PID 2>/dev/null
rm -f /tmp/api-smoke-output.log
```

---

## Report

```markdown
## Feature Validation: {entity_name}

| Check | Result | Details |
|-------|--------|---------|
| Solution build | {build_result} | |
| Unit tests | {unit_test_result} | {unit_test_count} passed |
| Integration tests | {integration_test_result} | {integration_test_count} passed |
| GET /api/{entity_code} | {status} | |
| POST /api/{entity_code} | {status} | |
| GET /api/{entity_code}/{id} | {status} | |
| PUT /api/{entity_code}/{id} | {status} | |
| DELETE /api/{entity_code}/{id} | {status} | |
| GET deleted entity | {status} | |

### Overall: {ALL_PASS or FAILURES_DETECTED}
```

---

## NEXT STEP:

Proceed to `./step-05-db-validation.md`