|
| 1 | +# API Endpoints Refactoring Guide |
| 2 | + |
| 3 | +This document explains how to refactor API URLs to use the centralized endpoints configuration. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +All API endpoints are now centralized in `src/api/endpoints.ts`. This makes it: |
| 8 | +- **Maintainable**: Change URLs in one place |
| 9 | +- **Type-safe**: TypeScript ensures correct usage |
| 10 | +- **Discoverable**: All endpoints are documented in one file |
| 11 | +- **Consistent**: No more typos or inconsistent paths |
| 12 | + |
| 13 | +## Usage Patterns |
| 14 | + |
| 15 | +### 1. Simple Static Endpoints |
| 16 | + |
| 17 | +**Before:** |
| 18 | +```typescript |
| 19 | +const url = `/api/v1/api/feedback/`; |
| 20 | +await publicApi.post(url, data); |
| 21 | +``` |
| 22 | + |
| 23 | +**After:** |
| 24 | +```typescript |
| 25 | +import { V1_API_ENDPOINTS } from "../api/endpoints"; |
| 26 | + |
| 27 | +await publicApi.post(V1_API_ENDPOINTS.FEEDBACK, data); |
| 28 | +``` |
| 29 | + |
| 30 | +### 2. Dynamic Endpoints with Parameters |
| 31 | + |
| 32 | +**Before:** |
| 33 | +```typescript |
| 34 | +const url = `/api/v1/api/uploadFile/${guid}`; |
| 35 | +await fetch(url); |
| 36 | +``` |
| 37 | + |
| 38 | +**After:** |
| 39 | +```typescript |
| 40 | +import { endpoints } from "../api/endpoints"; |
| 41 | + |
| 42 | +const url = endpoints.uploadFile(guid); |
| 43 | +await fetch(url); |
| 44 | +``` |
| 45 | + |
| 46 | +### 3. Endpoints with Query Parameters |
| 47 | + |
| 48 | +**Before:** |
| 49 | +```typescript |
| 50 | +const endpoint = guid |
| 51 | + ? `/api/v1/api/embeddings/ask_embeddings?guid=${guid}` |
| 52 | + : '/api/v1/api/embeddings/ask_embeddings'; |
| 53 | +``` |
| 54 | + |
| 55 | +**After:** |
| 56 | +```typescript |
| 57 | +import { endpoints } from "../api/endpoints"; |
| 58 | + |
| 59 | +const endpoint = endpoints.embeddingsAsk(guid); |
| 60 | +``` |
| 61 | + |
| 62 | +## Available Endpoint Groups |
| 63 | + |
| 64 | +### Authentication Endpoints |
| 65 | +```typescript |
| 66 | +import { AUTH_ENDPOINTS } from "../api/endpoints"; |
| 67 | + |
| 68 | +AUTH_ENDPOINTS.JWT_VERIFY |
| 69 | +AUTH_ENDPOINTS.JWT_CREATE |
| 70 | +AUTH_ENDPOINTS.USER_ME |
| 71 | +AUTH_ENDPOINTS.RESET_PASSWORD |
| 72 | +AUTH_ENDPOINTS.RESET_PASSWORD_CONFIRM |
| 73 | +``` |
| 74 | + |
| 75 | +### V1 API Endpoints |
| 76 | +```typescript |
| 77 | +import { V1_API_ENDPOINTS } from "../api/endpoints"; |
| 78 | + |
| 79 | +V1_API_ENDPOINTS.FEEDBACK |
| 80 | +V1_API_ENDPOINTS.UPLOAD_FILE |
| 81 | +V1_API_ENDPOINTS.GET_FULL_LIST_MED |
| 82 | +V1_API_ENDPOINTS.MED_RULES |
| 83 | +// ... and more |
| 84 | +``` |
| 85 | + |
| 86 | +### Conversation Endpoints |
| 87 | +```typescript |
| 88 | +import { CONVERSATION_ENDPOINTS } from "../api/endpoints"; |
| 89 | + |
| 90 | +CONVERSATION_ENDPOINTS.CONVERSATIONS |
| 91 | +CONVERSATION_ENDPOINTS.EXTRACT_TEXT |
| 92 | +``` |
| 93 | + |
| 94 | +### AI Settings Endpoints |
| 95 | +```typescript |
| 96 | +import { AI_SETTINGS_ENDPOINTS } from "../api/endpoints"; |
| 97 | + |
| 98 | +AI_SETTINGS_ENDPOINTS.SETTINGS |
| 99 | +``` |
| 100 | + |
| 101 | +### Helper Functions |
| 102 | +```typescript |
| 103 | +import { endpoints } from "../api/endpoints"; |
| 104 | + |
| 105 | +endpoints.embeddingsAsk(guid?) |
| 106 | +endpoints.embeddingsAskStream(guid?) |
| 107 | +endpoints.ruleExtraction(guid) |
| 108 | +endpoints.conversation(id) |
| 109 | +endpoints.continueConversation(id) |
| 110 | +endpoints.updateConversationTitle(id) |
| 111 | +endpoints.uploadFile(guid) |
| 112 | +endpoints.editMetadata(guid) |
| 113 | +``` |
| 114 | +
|
| 115 | +## Files to Refactor |
| 116 | +
|
| 117 | +The following files still need to be updated to use the centralized endpoints: |
| 118 | +
|
| 119 | +1. `src/pages/Settings/SettingsManager.tsx` - Use `AI_SETTINGS_ENDPOINTS.SETTINGS` |
| 120 | +2. `src/pages/RulesManager/RulesManager.tsx` - Use `V1_API_ENDPOINTS.MED_RULES` |
| 121 | +3. `src/pages/PatientManager/NewPatientForm.tsx` - Use `V1_API_ENDPOINTS.GET_MED_RECOMMEND` |
| 122 | +4. `src/pages/ManageMeds/ManageMeds.tsx` - Use `V1_API_ENDPOINTS.*` for all medication endpoints |
| 123 | +5. `src/pages/ListMeds/useMedications.tsx` - Use `V1_API_ENDPOINTS.GET_FULL_LIST_MED` |
| 124 | +6. `src/pages/Layout/Layout_V2_Sidebar.tsx` - Use `V1_API_ENDPOINTS.UPLOAD_FILE` |
| 125 | +7. `src/pages/Files/ListOfFiles.tsx` - Use `V1_API_ENDPOINTS.UPLOAD_FILE` |
| 126 | +8. `src/pages/DocumentManager/UploadFile.tsx` - Use `V1_API_ENDPOINTS.UPLOAD_FILE` |
| 127 | +9. `src/pages/Files/FileRow.tsx` - Use `endpoints.editMetadata(guid)` |
| 128 | +10. `src/pages/DrugSummary/PDFViewer.tsx` - Use `endpoints.uploadFile(guid)` |
| 129 | +11. `src/pages/PatientManager/PatientSummary.tsx` - Use `endpoints.uploadFile(guid)` |
| 130 | +
|
| 131 | +## Example Refactoring |
| 132 | +
|
| 133 | +### Example 1: SettingsManager.tsx |
| 134 | +
|
| 135 | +**Before:** |
| 136 | +```typescript |
| 137 | +const baseUrl = import.meta.env.VITE_API_BASE_URL || "http://localhost:8000"; |
| 138 | +const url = `${baseUrl}/ai_settings/settings/`; |
| 139 | +``` |
| 140 | +
|
| 141 | +**After:** |
| 142 | +```typescript |
| 143 | +import { AI_SETTINGS_ENDPOINTS } from "../../api/endpoints"; |
| 144 | + |
| 145 | +const url = AI_SETTINGS_ENDPOINTS.SETTINGS; |
| 146 | +``` |
| 147 | +
|
| 148 | +### Example 2: FileRow.tsx |
| 149 | +
|
| 150 | +**Before:** |
| 151 | +```typescript |
| 152 | +const baseUrl = import.meta.env.VITE_API_BASE_URL as string; |
| 153 | +await fetch(`${baseUrl}/v1/api/editmetadata/${file.guid}`, { |
| 154 | +``` |
| 155 | +
|
| 156 | +**After:** |
| 157 | +```typescript |
| 158 | +import { endpoints } from "../../api/endpoints"; |
| 159 | + |
| 160 | +await fetch(endpoints.editMetadata(file.guid), { |
| 161 | +``` |
| 162 | +
|
| 163 | +### Example 3: ManageMeds.tsx |
| 164 | +
|
| 165 | +**Before:** |
| 166 | +```typescript |
| 167 | +const baseUrl = import.meta.env.VITE_API_BASE_URL; |
| 168 | +const url = `${baseUrl}/v1/api/get_full_list_med`; |
| 169 | +await adminApi.delete(`${baseUrl}/v1/api/delete_med`, { data: { name } }); |
| 170 | +await adminApi.post(`${baseUrl}/v1/api/add_medication`, { ... }); |
| 171 | +``` |
| 172 | +
|
| 173 | +**After:** |
| 174 | +```typescript |
| 175 | +import { V1_API_ENDPOINTS } from "../../api/endpoints"; |
| 176 | + |
| 177 | +const url = V1_API_ENDPOINTS.GET_FULL_LIST_MED; |
| 178 | +await adminApi.delete(V1_API_ENDPOINTS.DELETE_MED, { data: { name } }); |
| 179 | +await adminApi.post(V1_API_ENDPOINTS.ADD_MEDICATION, { ... }); |
| 180 | +``` |
| 181 | +
|
| 182 | +## Benefits |
| 183 | +
|
| 184 | +1. **Single Source of Truth**: All endpoints defined in one place |
| 185 | +2. **Easy Updates**: Change an endpoint once, updates everywhere |
| 186 | +3. **Type Safety**: TypeScript catches typos and incorrect usage |
| 187 | +4. **Better IDE Support**: Autocomplete for all available endpoints |
| 188 | +5. **Documentation**: Endpoints are self-documenting with clear names |
| 189 | +6. **Refactoring Safety**: Rename endpoints safely across the codebase |
| 190 | +
|
| 191 | +## Adding New Endpoints |
| 192 | +
|
| 193 | +When adding a new endpoint: |
| 194 | +
|
| 195 | +1. Add it to the appropriate group in `src/api/endpoints.ts` |
| 196 | +2. If it needs dynamic parameters, add a helper function to `endpoints` object |
| 197 | +3. Use the new endpoint in your code |
| 198 | +4. Update this guide if needed |
| 199 | +
|
| 200 | +Example: |
| 201 | +```typescript |
| 202 | +// In endpoints.ts |
| 203 | +export const V1_API_ENDPOINTS = { |
| 204 | + // ... existing endpoints |
| 205 | + NEW_ENDPOINT: `${API_BASE}/v1/api/new_endpoint`, |
| 206 | +} as const; |
| 207 | + |
| 208 | +// If it needs parameters: |
| 209 | +export const endpoints = { |
| 210 | + // ... existing helpers |
| 211 | + newEndpoint: (id: string, param: string): string => { |
| 212 | + return `${V1_API_ENDPOINTS.NEW_ENDPOINT}/${id}?param=${param}`; |
| 213 | + }, |
| 214 | +} as const; |
| 215 | +``` |
| 216 | +
|
0 commit comments