116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
# V2 Backend API Guide
|
|
|
|
This is the frontend-facing source of truth for the v2 backend.
|
|
|
|
## 1) Use one base URL
|
|
|
|
Frontend should call one public gateway:
|
|
|
|
```env
|
|
API_V2_BASE_URL=https://krow-api-v2-933560802882.us-central1.run.app
|
|
```
|
|
|
|
Frontend should not call the internal `core`, `command`, or `query` Cloud Run services directly.
|
|
|
|
## 2) Current status
|
|
|
|
The unified v2 gateway is ready for frontend integration in `dev`.
|
|
|
|
What was validated live against the deployed stack:
|
|
|
|
- client sign-in
|
|
- staff auth bootstrap
|
|
- client dashboard, billing, coverage, hubs, vendors, managers, team members, orders, and reports
|
|
- client hub and order write flows
|
|
- client invoice approve and dispute
|
|
- staff dashboard, availability, payments, shifts, profile sections, documents, certificates, attire, bank accounts, benefits, and time card
|
|
- staff availability, profile, tax form, bank account, shift apply, shift accept, clock-in, clock-out, and swap request
|
|
- direct file upload helpers and verification job creation through the unified host
|
|
- client and staff sign-out
|
|
|
|
The live validation command is:
|
|
|
|
```bash
|
|
source ~/.nvm/nvm.sh
|
|
nvm use 23.5.0
|
|
node backend/unified-api/scripts/live-smoke-v2-unified.mjs
|
|
```
|
|
|
|
The demo tenant can be reset with:
|
|
|
|
```bash
|
|
source ~/.nvm/nvm.sh
|
|
nvm use 23.5.0
|
|
cd backend/command-api
|
|
npm run seed:v2-demo
|
|
```
|
|
|
|
## 3) Auth and headers
|
|
|
|
Protected routes require:
|
|
|
|
```http
|
|
Authorization: Bearer <firebase-id-token>
|
|
```
|
|
|
|
Write routes also require:
|
|
|
|
```http
|
|
Idempotency-Key: <unique-per-user-action>
|
|
```
|
|
|
|
For now:
|
|
|
|
- backend wraps sign-in and sign-out
|
|
- frontend can keep using Firebase token refresh on the client
|
|
- backend is the only thing frontend should call for session-oriented API flows
|
|
|
|
All routes return the same error envelope:
|
|
|
|
```json
|
|
{
|
|
"code": "STRING_CODE",
|
|
"message": "Human readable message",
|
|
"details": {},
|
|
"requestId": "uuid"
|
|
}
|
|
```
|
|
|
|
## 4) Route model
|
|
|
|
Frontend sees one base URL and one route shape:
|
|
|
|
- `/auth/*`
|
|
- `/client/*`
|
|
- `/staff/*`
|
|
- direct upload aliases like `/upload-file` and `/staff/profile/*`
|
|
|
|
Internally, the gateway still forwards to:
|
|
|
|
| Frontend use case | Internal service |
|
|
| --- | --- |
|
|
| auth/session wrapper | `krow-api-v2` |
|
|
| uploads, signed URLs, model calls, verification workflows | `core-api-v2` |
|
|
| writes and workflow actions | `command-api-v2` |
|
|
| reads and mobile read models | `query-api-v2` |
|
|
|
|
## 5) Frontend integration rule
|
|
|
|
Use the unified routes first.
|
|
|
|
Do not build new frontend work on:
|
|
|
|
- `/query/tenants/*`
|
|
- `/commands/*`
|
|
- `/core/*`
|
|
|
|
Those routes still exist for backend/internal compatibility, but mobile/frontend migration should target the unified surface documented in [Unified API](./unified-api.md).
|
|
|
|
## 6) Docs
|
|
|
|
- [Unified API](./unified-api.md)
|
|
- [Core API](./core-api.md)
|
|
- [Command API](./command-api.md)
|
|
- [Query API](./query-api.md)
|
|
- [Mobile API Reconciliation](./mobile-api-gap-analysis.md)
|