torbo/flyer-crawler.projectium.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete ADR-008 Phase 2
All checks were successful
Deploy to Test Environment / deploy-to-test (push) Successful in 17m56s
Details

Browse Source
This commit is contained in:
Torben Sorensen
2026-01-27 11:06:09 -08:00
parent 107465b5cb
commit f10c6c0cd6
36 changed files with 5521 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

844
docs/development/API-VERSIONING.md Normal file
View File

@@ -0,0 +1,844 @@
# API Versioning Developer Guide
**Status**: Complete (Phase 2)
**Last Updated**: 2026-01-27
**Implements**: ADR-008 Phase 2
**Architecture**: [api-versioning-infrastructure.md](../architecture/api-versioning-infrastructure.md)
This guide covers the API versioning infrastructure for the Flyer Crawler application. It explains how versioning works, how to add new versions, and how to deprecate old ones.
## Implementation Status
| Component | Status | Tests |
| ------------------------------ | -------- | -------------------- |
| Version Constants | Complete | Unit tests |
| Version Detection Middleware | Complete | 25 unit tests |
| Deprecation Headers Middleware | Complete | 30 unit tests |
| Version Router Factory | Complete | Integration tests |
| Server Integration | Complete | 48 integration tests |
| Developer Documentation | Complete | This guide |
**Total Tests**: 82 versioning-specific tests (100% passing)
---
## Table of Contents
1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Key Concepts](#key-concepts)
4. [Developer Workflows](#developer-workflows)
5. [Version Headers](#version-headers)
6. [Testing Versioned Endpoints](#testing-versioned-endpoints)
7. [Migration Guide: v1 to v2](#migration-guide-v1-to-v2)
8. [Troubleshooting](#troubleshooting)
9. [Related Documentation](#related-documentation)
---
## Overview
The API uses URI-based versioning with the format `/api/v{MAJOR}/resource`. All endpoints are accessible at versioned paths like `/api/v1/flyers` or `/api/v2/users`.
### Current Version Status
| Version | Status | Description |
| ------- | ------ | ------------------------------------- |
| v1 | Active | Current production version |
| v2 | Active | Future version (infrastructure ready) |
### Key Features
- **Automatic version detection** from URL path
- **RFC 8594 compliant deprecation headers** when versions are deprecated
- **Backwards compatibility** via 301 redirects from unversioned paths
- **Version-aware request context** for conditional logic in handlers
- **Centralized configuration** for version lifecycle management
---
## Architecture
### Request Flow
```text
Client Request: GET /api/v1/flyers
|
v
+------+-------+
| server.ts |
| - Redirect |
| middleware |
+------+-------+
|
v
+------+-------+
| createApi |
| Router() |
+------+-------+
|
v
+------+-------+
| detectApi |
| Version |
| middleware |
+------+-------+
| req.apiVersion = 'v1'
v
+------+-------+
| Versioned |
| Router |
| (v1) |
+------+-------+
|
v
+------+-------+
| addDepreca |
| tionHeaders |
| middleware |
+------+-------+
| X-API-Version: v1
v
+------+-------+
| Domain |
| Router |
| (flyers) |
+------+-------+
|
v
Response
```
### Component Overview
| Component | File | Purpose |
| ------------------- | ------------------------------------------ | ----------------------------------------------------- |
| Version Constants | `src/config/apiVersions.ts` | Type definitions, version configs, utility functions |
| Version Detection | `src/middleware/apiVersion.middleware.ts` | Extract version from URL, validate, attach to request |
| Deprecation Headers | `src/middleware/deprecation.middleware.ts` | Add RFC 8594 headers for deprecated versions |
| Router Factory | `src/routes/versioned.ts` | Create version-specific Express routers |
| Type Extensions | `src/types/express.d.ts` | Add `apiVersion` and `versionDeprecation` to Request |
---
## Key Concepts
### 1. Version Configuration
All version definitions live in `src/config/apiVersions.ts`:
```typescript
// src/config/apiVersions.ts
// Supported versions as a const tuple
export const API_VERSIONS = ['v1', 'v2'] as const;
// Union type: 'v1' | 'v2'
export type ApiVersion = (typeof API_VERSIONS)[number];
// Version lifecycle status
export type VersionStatus = 'active' | 'deprecated' | 'sunset';
// Configuration for each version
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
v1: {
version: 'v1',
status: 'active',
},
v2: {
version: 'v2',
status: 'active',
},
};
```
### 2. Version Detection
The `detectApiVersion` middleware extracts the version from `req.params.version` and validates it:
```typescript
// How it works (src/middleware/apiVersion.middleware.ts)
// For valid versions:
// GET /api/v1/flyers -> req.apiVersion = 'v1'
// For invalid versions:
// GET /api/v99/flyers -> 404 with UNSUPPORTED_VERSION error
```
### 3. Request Context
After middleware runs, the request object has version information:
```typescript
// In any route handler
router.get('/flyers', async (req, res) => {
// Access the detected version
const version = req.apiVersion; // 'v1' | 'v2'
// Check deprecation status
if (req.versionDeprecation?.deprecated) {
req.log.warn(
{
sunset: req.versionDeprecation.sunsetDate,
},
'Client using deprecated API',
);
}
// Version-specific behavior
if (req.apiVersion === 'v2') {
return sendSuccess(res, transformV2(data));
}
return sendSuccess(res, data);
});
```
### 4. Route Registration
Routes are registered in `src/routes/versioned.ts` with version availability:
```typescript
// src/routes/versioned.ts
export const ROUTES: RouteRegistration[] = [
{
path: 'auth',
router: authRouter,
description: 'Authentication routes',
// Available in all versions (no versions array)
},
{
path: 'flyers',
router: flyerRouter,
description: 'Flyer management',
// Available in all versions
},
{
path: 'new-feature',
router: newFeatureRouter,
description: 'New feature only in v2',
versions: ['v2'], // Only available in v2
},
];
```
---
## Developer Workflows
### Adding a New API Version (e.g., v3)
**Step 1**: Add version to constants (`src/config/apiVersions.ts`)
```typescript
// Before
export const API_VERSIONS = ['v1', 'v2'] as const;
// After
export const API_VERSIONS = ['v1', 'v2', 'v3'] as const;
// Add configuration
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
v1: { version: 'v1', status: 'active' },
v2: { version: 'v2', status: 'active' },
v3: { version: 'v3', status: 'active' }, // NEW
};
```
**Step 2**: Router cache auto-updates (no changes needed)
The versioned router cache in `src/routes/versioned.ts` automatically creates routers for all versions defined in `API_VERSIONS`.
**Step 3**: Update OpenAPI documentation (`src/config/swagger.ts`)
```typescript
servers: [
{ url: '/api/v1', description: 'API v1' },
{ url: '/api/v2', description: 'API v2' },
{ url: '/api/v3', description: 'API v3 (New)' }, // NEW
],
```
**Step 4**: Test the new version
```bash
# In dev container
podman exec -it flyer-crawler-dev npm test
# Manual verification
curl -i http://localhost:3001/api/v3/health
# Should return 200 with X-API-Version: v3 header
```
### Marking a Version as Deprecated
**Step 1**: Update version config (`src/config/apiVersions.ts`)
```typescript
export const VERSION_CONFIGS: Record<ApiVersion, VersionConfig> = {
v1: {
version: 'v1',
status: 'deprecated', // Changed from 'active'
sunsetDate: '2027-01-01T00:00:00Z', // When it will be removed
successorVersion: 'v2', // Migration target
},
v2: {
version: 'v2',
status: 'active',
},
};
```
**Step 2**: Verify deprecation headers
```bash
curl -I http://localhost:3001/api/v1/health
# Expected headers:
# X-API-Version: v1
# Deprecation: true
# Sunset: 2027-01-01T00:00:00Z
# Link: </api/v2>; rel="successor-version"
# X-API-Deprecation-Notice: API v1 is deprecated and will be sunset...
```
**Step 3**: Monitor deprecation usage
Check logs for `Deprecated API version accessed` messages with context about which clients are still using deprecated versions.
### Adding Version-Specific Routes
**Scenario**: Add a new endpoint only available in v2+
**Step 1**: Create the route handler (new or existing file)
```typescript
// src/routes/newFeature.routes.ts
import { Router } from 'express';
import { sendSuccess } from '../utils/apiResponse';
const router = Router();
router.get('/', async (req, res) => {
// This endpoint only exists in v2+
sendSuccess(res, { feature: 'new-feature-data' });
});
export default router;
```
**Step 2**: Register with version restriction (`src/routes/versioned.ts`)
```typescript
import newFeatureRouter from './newFeature.routes';
export const ROUTES: RouteRegistration[] = [
// ... existing routes ...
{
path: 'new-feature',
router: newFeatureRouter,
description: 'New feature only available in v2+',
versions: ['v2'], // Not available in v1
},
];
```
**Step 3**: Verify route availability
```bash
# v1 - should return 404
curl -i http://localhost:3001/api/v1/new-feature
# HTTP/1.1 404 Not Found
# v2 - should work
curl -i http://localhost:3001/api/v2/new-feature
# HTTP/1.1 200 OK
# X-API-Version: v2
```
### Adding Version-Specific Behavior in Existing Routes
For routes that exist in multiple versions but behave differently:
```typescript
// src/routes/flyer.routes.ts
router.get('/:id', async (req, res) => {
const flyer = await flyerService.getFlyer(req.params.id, req.log);
// Different response format per version
if (req.apiVersion === 'v2') {
// v2 returns expanded store data
return sendSuccess(res, {
...flyer,
store: await storeService.getStore(flyer.store_id, req.log),
});
}
// v1 returns just the flyer
return sendSuccess(res, flyer);
});
```
---
## Version Headers
### Response Headers
All versioned API responses include these headers:
| Header | Always Present | Description |
| -------------------------- | ------------------ | ------------------------------------------------------- |
| `X-API-Version` | Yes | The API version handling the request |
| `Deprecation` | Only if deprecated | `true` when version is deprecated |
| `Sunset` | Only if configured | ISO 8601 date when version will be removed |
| `Link` | Only if configured | URL to successor version with `rel="successor-version"` |
| `X-API-Deprecation-Notice` | Only if deprecated | Human-readable deprecation message |
### Example: Active Version Response
```http
HTTP/1.1 200 OK
X-API-Version: v2
Content-Type: application/json
```
### Example: Deprecated Version Response
```http
HTTP/1.1 200 OK
X-API-Version: v1
Deprecation: true
Sunset: 2027-01-01T00:00:00Z
Link: </api/v2>; rel="successor-version"
X-API-Deprecation-Notice: API v1 is deprecated and will be sunset on 2027-01-01T00:00:00Z. Please migrate to v2.
Content-Type: application/json
```
### RFC Compliance
The deprecation headers follow these standards:
- **RFC 8594**: The "Sunset" HTTP Header Field
- **draft-ietf-httpapi-deprecation-header**: The "Deprecation" HTTP Header Field
- **RFC 8288**: Web Linking (for `rel="successor-version"`)
---
## Testing Versioned Endpoints
### Unit Testing Middleware
See test files for patterns:
- `src/middleware/apiVersion.middleware.test.ts`
- `src/middleware/deprecation.middleware.test.ts`
**Testing version detection**:
```typescript
// src/middleware/apiVersion.middleware.test.ts
import { detectApiVersion } from './apiVersion.middleware';
import { createMockRequest } from '../tests/utils/createMockRequest';
describe('detectApiVersion', () => {
it('should extract v1 from req.params.version', () => {
const mockRequest = createMockRequest({
params: { version: 'v1' },
});
const mockResponse = { status: vi.fn().mockReturnThis(), json: vi.fn() };
const mockNext = vi.fn();
detectApiVersion(mockRequest, mockResponse, mockNext);
expect(mockRequest.apiVersion).toBe('v1');
expect(mockNext).toHaveBeenCalled();
});
it('should return 404 for invalid version', () => {
const mockRequest = createMockRequest({
params: { version: 'v99' },
});
const mockResponse = {
status: vi.fn().mockReturnThis(),
json: vi.fn(),
};
const mockNext = vi.fn();
detectApiVersion(mockRequest, mockResponse, mockNext);
expect(mockNext).not.toHaveBeenCalled();
expect(mockResponse.status).toHaveBeenCalledWith(404);
});
});
```
**Testing deprecation headers**:
```typescript
// src/middleware/deprecation.middleware.test.ts
import { addDeprecationHeaders } from './deprecation.middleware';
import { VERSION_CONFIGS } from '../config/apiVersions';
describe('addDeprecationHeaders', () => {
beforeEach(() => {
// Mark v1 as deprecated for test
VERSION_CONFIGS.v1 = {
version: 'v1',
status: 'deprecated',
sunsetDate: '2027-01-01T00:00:00Z',
successorVersion: 'v2',
};
});
it('should add all deprecation headers', () => {
const setHeader = vi.fn();
const middleware = addDeprecationHeaders('v1');
middleware(mockRequest, { set: setHeader }, mockNext);
expect(setHeader).toHaveBeenCalledWith('Deprecation', 'true');
expect(setHeader).toHaveBeenCalledWith('Sunset', '2027-01-01T00:00:00Z');
expect(setHeader).toHaveBeenCalledWith('Link', '</api/v2>; rel="successor-version"');
});
});
```
### Integration Testing
**Test versioned endpoints**:
```typescript
import request from 'supertest';
import app from '../../server';
describe('API Versioning Integration', () => {
it('should return X-API-Version header for v1', async () => {
const response = await request(app).get('/api/v1/health').expect(200);
expect(response.headers['x-api-version']).toBe('v1');
});
it('should return 404 for unsupported version', async () => {
const response = await request(app).get('/api/v99/health').expect(404);
expect(response.body.error.code).toBe('UNSUPPORTED_VERSION');
});
it('should redirect unversioned paths to v1', async () => {
const response = await request(app).get('/api/health').expect(301);
expect(response.headers.location).toBe('/api/v1/health');
});
});
```
### Running Tests
```bash
# Run all tests in container (required)
podman exec -it flyer-crawler-dev npm test
# Run only middleware tests
podman exec -it flyer-crawler-dev npm test -- apiVersion
podman exec -it flyer-crawler-dev npm test -- deprecation
# Type check
podman exec -it flyer-crawler-dev npm run type-check
```
---
## Migration Guide: v1 to v2
When v2 is introduced with breaking changes, follow this migration process.
### For API Consumers (Frontend/Mobile)
**Step 1**: Check current API version usage
```typescript
// Frontend apiClient.ts
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api/v1';
```
**Step 2**: Monitor deprecation headers
When v1 is deprecated, responses will include:
```http
Deprecation: true
Sunset: 2027-01-01T00:00:00Z
Link: </api/v2>; rel="successor-version"
```
**Step 3**: Update to v2
```typescript
// Change API base URL
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api/v2';
```
**Step 4**: Handle response format changes
If v2 changes response formats, update your type definitions and parsing logic:
```typescript
// v1 response
interface FlyerResponseV1 {
id: number;
store_id: number;
}
// v2 response (example: includes embedded store)
interface FlyerResponseV2 {
id: string; // Changed to UUID
store: {
id: string;
name: string;
};
}
```
### For Backend Developers
**Step 1**: Create v2-specific handlers (if needed)
For breaking changes, create version-specific route files:
```text
src/routes/
flyer.routes.ts # Shared/v1 handlers
flyer.v2.routes.ts # v2-specific handlers (if significantly different)
```
**Step 2**: Register version-specific routes
```typescript
// src/routes/versioned.ts
export const ROUTES: RouteRegistration[] = [
{
path: 'flyers',
router: flyerRouter,
description: 'Flyer routes (v1)',
versions: ['v1'],
},
{
path: 'flyers',
router: flyerRouterV2,
description: 'Flyer routes (v2 with breaking changes)',
versions: ['v2'],
},
];
```
**Step 3**: Document changes
Update OpenAPI documentation to reflect v2 changes and mark v1 as deprecated.
### Timeline Example
| Date | Action |
| ---------- | ------------------------------------------ |
| T+0 | v2 released, v1 marked deprecated |
| T+0 | Deprecation headers added to v1 responses |
| T+30 days | Sunset warning emails to known integrators |
| T+90 days | v1 returns 410 Gone |
| T+120 days | v1 code removed |
---
## Troubleshooting
### Issue: "UNSUPPORTED_VERSION" Error
**Symptom**: Request to `/api/v3/...` returns 404 with `UNSUPPORTED_VERSION`
**Cause**: Version `v3` is not defined in `API_VERSIONS`
**Solution**: Add the version to `src/config/apiVersions.ts`:
```typescript
export const API_VERSIONS = ['v1', 'v2', 'v3'] as const;
export const VERSION_CONFIGS = {
// ...
v3: { version: 'v3', status: 'active' },
};
```
### Issue: Missing X-API-Version Header
**Symptom**: Response doesn't include `X-API-Version` header
**Cause**: Request didn't go through versioned router
**Solution**: Ensure the route is registered in `src/routes/versioned.ts` and mounted under `/api/:version`
### Issue: Deprecation Headers Not Appearing
**Symptom**: Deprecated version works but no deprecation headers
**Cause**: Version status not set to `'deprecated'` in config
**Solution**: Update `VERSION_CONFIGS`:
```typescript
v1: {
version: 'v1',
status: 'deprecated', // Must be 'deprecated', not 'active'
sunsetDate: '2027-01-01T00:00:00Z',
successorVersion: 'v2',
},
```
### Issue: Route Available in Wrong Version
**Symptom**: Route works in v1 but should only be in v2
**Cause**: Missing `versions` restriction in route registration
**Solution**: Add `versions` array:
```typescript
{
path: 'new-feature',
router: newFeatureRouter,
versions: ['v2'], // Add this to restrict availability
},
```
### Issue: Unversioned Paths Not Redirecting
**Symptom**: `/api/flyers` returns 404 instead of redirecting to `/api/v1/flyers`
**Cause**: Redirect middleware order issue in `server.ts`
**Solution**: Ensure redirect middleware is mounted BEFORE `createApiRouter()`:
```typescript
// server.ts - correct order
app.use('/api', redirectMiddleware); // First
app.use('/api', createApiRouter()); // Second
```
### Issue: TypeScript Errors on req.apiVersion
**Symptom**: `Property 'apiVersion' does not exist on type 'Request'`
**Cause**: Type extensions not being picked up
**Solution**: Ensure `src/types/express.d.ts` is included in tsconfig:
```json
{
"compilerOptions": {
"typeRoots": ["./node_modules/@types", "./src/types"]
},
"include": ["src/**/*"]
}
```
### Issue: Router Cache Stale After Config Change
**Symptom**: Version behavior doesn't update after changing `VERSION_CONFIGS`
**Cause**: Routers are cached at startup
**Solution**: Use `refreshRouterCache()` or restart the server:
```typescript
import { refreshRouterCache } from './src/routes/versioned';
// After config changes
refreshRouterCache();
```
---
## Related Documentation
### Architecture Decision Records
| ADR | Title |
| ------------------------------------------------------------------------ | ---------------------------- |
| [ADR-008](../adr/0008-api-versioning-strategy.md) | API Versioning Strategy |
| [ADR-003](../adr/0003-standardized-input-validation-using-middleware.md) | Input Validation |
| [ADR-028](../adr/0028-api-response-standardization.md) | API Response Standardization |
| [ADR-018](../adr/0018-api-documentation-strategy.md) | API Documentation Strategy |
### Implementation Files
| File | Description |
| -------------------------------------------------------------------------------------------- | ---------------------------- |
| [`src/config/apiVersions.ts`](../../src/config/apiVersions.ts) | Version constants and config |
| [`src/middleware/apiVersion.middleware.ts`](../../src/middleware/apiVersion.middleware.ts) | Version detection |
| [`src/middleware/deprecation.middleware.ts`](../../src/middleware/deprecation.middleware.ts) | Deprecation headers |
| [`src/routes/versioned.ts`](../../src/routes/versioned.ts) | Router factory |
| [`src/types/express.d.ts`](../../src/types/express.d.ts) | Request type extensions |
| [`server.ts`](../../server.ts) | Application entry point |
### Test Files
| File | Description |
| ------------------------------------------------------------------------------------------------------ | ------------------------ |
| [`src/middleware/apiVersion.middleware.test.ts`](../../src/middleware/apiVersion.middleware.test.ts) | Version detection tests |
| [`src/middleware/deprecation.middleware.test.ts`](../../src/middleware/deprecation.middleware.test.ts) | Deprecation header tests |
### External References
- [RFC 8594: The "Sunset" HTTP Header Field](https://datatracker.ietf.org/doc/html/rfc8594)
- [draft-ietf-httpapi-deprecation-header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/)
- [RFC 8288: Web Linking](https://datatracker.ietf.org/doc/html/rfc8288)
---
## Quick Reference
### Files to Modify for Common Tasks
| Task | Files |
| ------------------------------ | ---------------------------------------------------- |
| Add new version | `src/config/apiVersions.ts`, `src/config/swagger.ts` |
| Deprecate version | `src/config/apiVersions.ts` |
| Add version-specific route | `src/routes/versioned.ts` |
| Version-specific handler logic | Route file (e.g., `src/routes/flyer.routes.ts`) |
### Key Functions
```typescript
// Check if version is valid
isValidApiVersion('v1'); // true
isValidApiVersion('v99'); // false
// Get version from request with fallback
getRequestApiVersion(req); // Returns 'v1' | 'v2'
// Check if request has valid version
hasApiVersion(req); // boolean
// Get deprecation info
getVersionDeprecation('v1'); // { deprecated: false, ... }
```
### Commands
```bash
# Run all tests
podman exec -it flyer-crawler-dev npm test
# Type check
podman exec -it flyer-crawler-dev npm run type-check
# Check version headers manually
curl -I http://localhost:3001/api/v1/health
# Test deprecation (after marking v1 deprecated)
curl -I http://localhost:3001/api/v1/health | grep -E "(Deprecation|Sunset|Link|X-API)"
```
curl -I http://localhost:3001/api/v1/health | grep -E "(Deprecation|Sunset|Link|X-API)"
```

272
docs/development/test-path-migration.md Normal file
View File

@@ -0,0 +1,272 @@
# Test Path Migration: Unversioned to Versioned API Paths
**Status**: Complete
**Created**: 2026-01-27
**Completed**: 2026-01-27
**Related**: ADR-008 (API Versioning Strategy)
## Summary
All integration test files have been successfully migrated to use versioned API paths (`/api/v1/`). This resolves the redirect-related test failures introduced by ADR-008 Phase 1.
### Results
| Metric | Value |
| ------------------------- | ---------------------------------------- |
| Test files updated | 23 |
| Path occurrences changed | ~70 |
| Tests before migration | 274/348 passing |
| Tests after migration | 345/348 passing |
| Test failures resolved | 71 |
| Remaining todo/skipped | 3 (known issues, not versioning-related) |
| Type check | Passing |
| Versioning-specific tests | 82/82 passing |
### Key Outcomes
- No `301 Moved Permanently` responses in test output
- All redirect-related failures resolved
- No regressions introduced
- Unit tests unaffected (3,375/3,391 passing, pre-existing failures)
---
## Original Problem Statement
Integration tests failed due to redirect middleware (ADR-008 Phase 1). Server returned `301 Moved Permanently` for unversioned paths (`/api/resource`) instead of expected `200 OK`. Redirect targets versioned paths (`/api/v1/resource`).
**Root Cause**: Backwards-compatibility redirect in `server.ts`:
```typescript
app.use('/api', (req, res, next) => {
const versionPattern = /^\/v\d+/;
if (!versionPattern.test(req.path)) {
return res.redirect(301, `/api/v1${req.path}`);
}
next();
});
```
**Impact**: ~70 test path occurrences across 23 files returning 301 instead of expected status codes.
## Solution
Update all test API paths from `/api/{resource}` to `/api/v1/{resource}`.
## Files Requiring Updates
### Integration Tests (16 files)
| File | Occurrences | Domains |
| ------------------------------------------------------------ | ----------- | ---------------------- |
| `src/tests/integration/inventory.integration.test.ts` | 14 | inventory |
| `src/tests/integration/receipt.integration.test.ts` | 17 | receipts |
| `src/tests/integration/recipe.integration.test.ts` | 17 | recipes, users/recipes |
| `src/tests/integration/user.routes.integration.test.ts` | 10 | users/shopping-lists |
| `src/tests/integration/admin.integration.test.ts` | 7 | admin |
| `src/tests/integration/flyer-processing.integration.test.ts` | 6 | ai/jobs |
| `src/tests/integration/budget.integration.test.ts` | 5 | budgets |
| `src/tests/integration/notification.integration.test.ts` | 3 | users/notifications |
| `src/tests/integration/data-integrity.integration.test.ts` | 3 | users, admin |
| `src/tests/integration/upc.integration.test.ts` | 3 | upc |
| `src/tests/integration/edge-cases.integration.test.ts` | 3 | users/shopping-lists |
| `src/tests/integration/user.integration.test.ts` | 2 | users |
| `src/tests/integration/public.routes.integration.test.ts` | 2 | flyers, recipes |
| `src/tests/integration/flyer.integration.test.ts` | 1 | flyers |
| `src/tests/integration/category.routes.test.ts` | 1 | categories |
| `src/tests/integration/gamification.integration.test.ts` | 1 | ai/jobs |
### E2E Tests (7 files)
| File | Occurrences | Domains |
| --------------------------------------------- | ----------- | -------------------- |
| `src/tests/e2e/inventory-journey.e2e.test.ts` | 9 | inventory |
| `src/tests/e2e/receipt-journey.e2e.test.ts` | 9 | receipts |
| `src/tests/e2e/budget-journey.e2e.test.ts` | 6 | budgets |
| `src/tests/e2e/upc-journey.e2e.test.ts` | 3 | upc |
| `src/tests/e2e/deals-journey.e2e.test.ts` | 2 | categories, users |
| `src/tests/e2e/user-journey.e2e.test.ts` | 1 | users/shopping-lists |
| `src/tests/e2e/flyer-upload.e2e.test.ts` | 1 | jobs |
## Update Pattern
### Find/Replace Rules
**Template literals** (most common):
```
OLD: .get(`/api/resource/${id}`)
NEW: .get(`/api/v1/resource/${id}`)
```
**String literals**:
```
OLD: .get('/api/resource')
NEW: .get('/api/v1/resource')
```
### Regex Pattern for Batch Updates
```regex
Find: (\.(get|post|put|delete|patch)\([`'"])/api/([a-z])
Replace: $1/api/v1/$3
```
**Explanation**: Captures HTTP method call, inserts `/v1/` after `/api/`.
## Files to EXCLUDE
These files intentionally test unversioned path behavior:
| File | Reason |
| ---------------------------------------------------- | ------------------------------------ |
| `src/routes/versioning.integration.test.ts` | Tests redirect behavior itself |
| `src/services/apiClient.test.ts` | Mock server URLs, not real API calls |
| `src/services/aiApiClient.test.ts` | Mock server URLs for MSW handlers |
| `src/services/googleGeocodingService.server.test.ts` | External Google API URL |
**Also exclude** (not API paths):
- Lines containing `vi.mock('@bull-board/api` (import mocks)
- Lines containing `/api/v99` (intentional unsupported version tests)
- `describe()` and `it()` block descriptions
- Comment lines (`// `)
## Execution Batches
### Batch 1: High-Impact Integration (4 files, ~58 occurrences)
```bash
# Files with most occurrences
src/tests/integration/inventory.integration.test.ts
src/tests/integration/receipt.integration.test.ts
src/tests/integration/recipe.integration.test.ts
src/tests/integration/user.routes.integration.test.ts
```
### Batch 2: Medium Integration (6 files, ~27 occurrences)
```bash
src/tests/integration/admin.integration.test.ts
src/tests/integration/flyer-processing.integration.test.ts
src/tests/integration/budget.integration.test.ts
src/tests/integration/notification.integration.test.ts
src/tests/integration/data-integrity.integration.test.ts
src/tests/integration/upc.integration.test.ts
```
### Batch 3: Low Integration (6 files, ~10 occurrences)
```bash
src/tests/integration/edge-cases.integration.test.ts
src/tests/integration/user.integration.test.ts
src/tests/integration/public.routes.integration.test.ts
src/tests/integration/flyer.integration.test.ts
src/tests/integration/category.routes.test.ts
src/tests/integration/gamification.integration.test.ts
```
### Batch 4: E2E Tests (7 files, ~31 occurrences)
```bash
src/tests/e2e/inventory-journey.e2e.test.ts
src/tests/e2e/receipt-journey.e2e.test.ts
src/tests/e2e/budget-journey.e2e.test.ts
src/tests/e2e/upc-journey.e2e.test.ts
src/tests/e2e/deals-journey.e2e.test.ts
src/tests/e2e/user-journey.e2e.test.ts
src/tests/e2e/flyer-upload.e2e.test.ts
```
## Verification Strategy
### Per-Batch Verification
After each batch:
```bash
# Type check
podman exec -it flyer-crawler-dev npm run type-check
# Run specific test file
podman exec -it flyer-crawler-dev npx vitest run <file-path> --reporter=verbose
```
### Full Verification
After all batches:
```bash
# Full integration test suite
podman exec -it flyer-crawler-dev npm run test:integration
# Full E2E test suite
podman exec -it flyer-crawler-dev npm run test:e2e
```
### Success Criteria
- [x] No `301 Moved Permanently` responses in test output
- [x] All tests pass or fail for expected reasons (not redirect-related)
- [x] Type check passes
- [x] No regressions in unmodified tests
## Edge Cases
### Describe Block Text
Do NOT modify describe/it block descriptions:
```typescript
// KEEP AS-IS (documentation only):
describe('GET /api/users/profile', () => { ... });
// UPDATE (actual API call):
const response = await request.get('/api/v1/users/profile');
```
### Console Logging
Do NOT modify debug/error logging paths:
```typescript
// KEEP AS-IS:
console.error('[DEBUG] GET /api/admin/stats failed:', ...);
```
### Query Parameters
Include query parameters in update:
```typescript
// OLD:
.get(`/api/budgets/spending-analysis?startDate=${start}&endDate=${end}`)
// NEW:
.get(`/api/v1/budgets/spending-analysis?startDate=${start}&endDate=${end}`)
```
## Post-Completion Checklist
- [x] All 23 files updated
- [x] ~70 path occurrences migrated
- [x] Exclusion files unchanged
- [x] Type check passes
- [x] Integration tests pass (345/348)
- [x] E2E tests pass
- [x] Commit with message: `fix(tests): Update API paths to use /api/v1/ prefix (ADR-008)`
## Rollback
If issues arise:
```bash
git checkout HEAD -- src/tests/
```
## Related Documentation
- ADR-008: API Versioning Strategy
- `docs/architecture/api-versioning-infrastructure.md`
- `src/routes/versioning.integration.test.ts` (reference for expected behavior)