-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathroutingExplained
More file actions
178 lines (155 loc) · 11.3 KB
/
routingExplained
File metadata and controls
178 lines (155 loc) · 11.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
⏺ Routes → Endpoints Relationship Explained
Visual Hierarchy
┌─────────────────────────────────────────────────────────────┐
│ INCOMING REQUEST │
│ GET /api/knowi?key=xxx&page=1 │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ KEY (Required) │
│ ┌─────────────────────────┐ │
│ │ keyValue: "7d789c71..." │ │
│ │ isActive: true │ │
│ │ expiresAt: null │ │
│ └─────────────────────────┘ │
└───────────────┬───────────────┘
│ Validates
▼
┌───────────────────────────────┐
│ ROUTE (Required) │
│ ┌─────────────────────────┐ │
│ │ path: "/api/knowi" │ │
│ │ method: "GET" │ │
│ │ requiresAuth: true │ │
│ │ function: [REF] ────────┼──┐
│ │ endpoint: [REF or NULL] │ │
│ └─────────────────────────┘ │
└───────────────┬───────────────┘
│
┌────────────┴────────────┐
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ FUNCTION (Req'd) │ │ ENDPOINT (Opt.) │
│ ┌──────────────┐ │ │ ┌──────────────┐ │
│ │ name: "..." │ │ │ │ baseUrl: ... │ │
│ │ service: │ │ │ │ headers: ... │ │
│ │ "knowi" │ │ │ │ timeout: ... │ │
│ │ code/path │ │ │ └──────────────┘ │
│ └──────────────┘ │ └──────────────────┘
└────────┬─────────┘ │
│ │
│ Executes │ Used if present
▼ ▼
┌──────────────────────────────────┐
│ BUSINESS LOGIC │
└──────────────────────────────────┘
Three Route Patterns
Pattern 1: Internal Database Query (No Endpoint Needed)
┌──────────────────────────────────────────────────────────────┐
│ Route: /api/knowi │
├──────────────────────────────────────────────────────────────┤
│ Function: knowiHandler │
│ ├─ Connects to MySQL directly │
│ ├─ Queries rdi_business database │
│ └─ Returns paginated results │
├──────────────────────────────────────────────────────────────┤
│ Endpoint: NULL ❌ │
│ └─ Not needed - direct DB access │
└──────────────────────────────────────────────────────────────┘
Flow:
Request → Route → Function → MySQL Database → Response
↓
(uses env vars)
RDI_BUSINESS_DB_HOST
RDI_BUSINESS_DB_USERNAME
Pattern 2: External API Call (Endpoint Required)
┌──────────────────────────────────────────────────────────────┐
│ Route: /api/filemaker/search │
├──────────────────────────────────────────────────────────────┤
│ Function: filemakerSearch │
│ ├─ Builds FileMaker query │
│ ├─ Uses endpoint config for connection │
│ └─ Transforms response │
├──────────────────────────────────────────────────────────────┤
│ Endpoint: FileMaker Production ✅ │
│ ├─ baseUrl: "https://fm.company.com/fmi/data/v1" │
│ ├─ headers: { "Authorization": "Bearer ..." } │
│ ├─ timeout: 30000 │
│ └─ environment: "production" │
└──────────────────────────────────────────────────────────────┘
Flow:
Request → Route → Function → Endpoint Config → FileMaker Server
↓ ↓
(business logic) (connection)
Pattern 3: Pure Logic (No Endpoint Needed)
┌──────────────────────────────────────────────────────────────┐
│ Route: /api/health │
├──────────────────────────────────────────────────────────────┤
│ Function: healthCheck │
│ ├─ Checks internal services │
│ ├─ Returns status object │
│ └─ No external calls │
├──────────────────────────────────────────────────────────────┤
│ Endpoint: NULL ❌ │
│ └─ Pure computation │
└──────────────────────────────────────────────────────────────┘
Flow:
Request → Route → Function → Response
↓
(logic only)
When to Use Endpoint
┌─────────────────────────────────────────────────────────┐
│ DECISION TREE: Do I need an Endpoint? │
└─────────────────────────────────────────────────────────┘
Does your Function call an EXTERNAL API/service?
│
┌───────────┴───────────┐
│ │
YES NO
│ │
▼ ▼
Need Endpoint No Endpoint
✅ Use it ❌ Leave null
│ │
├─ FileMaker ├─ Direct DB query
├─ OpenAI API ├─ Redis cache
├─ Stripe API ├─ File system
├─ External REST ├─ Pure logic
└─ Third-party └─ Internal calc
Real-World Example Matrix
| Route Path | Function | Needs Endpoint? | Why? |
|----------------------|---------------|-----------------|-------------------------------------------|
| /api/knowi | knowiHandler | ❌ No | Direct MySQL connection via env vars |
| /api/gpt/chat | gptHandler | ✅ Yes | Calls OpenAI API - needs baseUrl, headers |
| /api/filemaker/query | fmQuery | ✅ Yes | Calls FileMaker - needs auth, base URL |
| /api/health | healthCheck | ❌ No | Returns {status: "ok"} - no external call |
| /api/transform | dataTransform | ❌ No | Pure data manipulation |
| /api/stripe/webhook | stripeWebhook | ✅ Yes | May call back to Stripe API |
Current /api/knowi Implementation
Route: /api/knowi
├─ path: "/api/knowi"
├─ method: "GET"
├─ requiresAuth: true
├─ function: knowiHandler ──────┐
└─ endpoint: null ❌ │
│
▼
Function: knowiHandler
├─ import knowiDb from '@/services/knowi/knowiDb.js'
├─ const result = await knowiDb.getPaginatedKnowiRecords()
└─ return Response.json(result)
↓
knowiDb.js
├─ Uses process.env.RDI_BUSINESS_DB_HOST
├─ Direct MySQL connection
└─ No HTTP call needed
Summary
Endpoint is optional because:
1. Not all routes call external services - Some query internal databases, some do pure logic
2. Different connection methods - DB connections use env vars, external APIs use Endpoint config
3. Flexibility - Simple routes shouldn't require creating unused Endpoint records
Endpoint is used when:
- Function needs to call external HTTP APIs
- You want to manage multiple environments (dev/staging/prod)
- Connection details (URL, headers, timeout) should be configurable in admin