121 lines
2.9 KiB
Markdown
121 lines
2.9 KiB
Markdown
# V2 Backend API Guide
|
|
|
|
This is the frontend-facing source of truth for the v2 backend.
|
|
|
|
If you are building against the new backend, start here.
|
|
|
|
## 1) Which service to use
|
|
|
|
| Use case | Service |
|
|
| --- | --- |
|
|
| File upload, signed URLs, model calls, rapid order helpers, verification flows | `core-api-v2` |
|
|
| Business writes and workflow actions | `command-api-v2` |
|
|
| Screen reads for the implemented v2 views | `query-api-v2` |
|
|
|
|
## 2) Live dev base URLs
|
|
|
|
- Core API: `https://krow-core-api-v2-e3g6witsvq-uc.a.run.app`
|
|
- Command API: `https://krow-command-api-v2-e3g6witsvq-uc.a.run.app`
|
|
- Query API: `https://krow-query-api-v2-e3g6witsvq-uc.a.run.app`
|
|
|
|
## 3) Auth and headers
|
|
|
|
All protected routes require:
|
|
|
|
```http
|
|
Authorization: Bearer <firebase-id-token>
|
|
```
|
|
|
|
All command routes also require:
|
|
|
|
```http
|
|
Idempotency-Key: <unique-per-user-action>
|
|
```
|
|
|
|
All services return the same error envelope:
|
|
|
|
```json
|
|
{
|
|
"code": "STRING_CODE",
|
|
"message": "Human readable message",
|
|
"details": {},
|
|
"requestId": "uuid"
|
|
}
|
|
```
|
|
|
|
## 4) What frontend can use now
|
|
|
|
### Ready now
|
|
|
|
- `core-api-v2`
|
|
- upload file
|
|
- create signed URL
|
|
- invoke model
|
|
- rapid order transcribe
|
|
- rapid order parse
|
|
- create verification
|
|
- get verification
|
|
- review verification
|
|
- retry verification
|
|
- `command-api-v2`
|
|
- create order
|
|
- update order
|
|
- cancel order
|
|
- assign staff to shift
|
|
- accept shift
|
|
- change shift status
|
|
- clock in
|
|
- clock out
|
|
- favorite and unfavorite staff
|
|
- create staff review
|
|
- `query-api-v2`
|
|
- order list
|
|
- order detail
|
|
- favorite staff list
|
|
- staff review summary
|
|
- assignment attendance detail
|
|
|
|
### Do not move yet
|
|
|
|
- reports
|
|
- payments and finance screens
|
|
- undocumented dashboard reads
|
|
- undocumented scheduling reads and writes
|
|
- any flow that assumes verification history is durable in SQL
|
|
|
|
## 5) Important caveat
|
|
|
|
`core-api-v2` is usable now, but verification job state is not yet persisted to `krow-sql-v2`.
|
|
|
|
What is durable today:
|
|
- uploaded files in Google Cloud Storage
|
|
- generated signed URLs
|
|
- model invocation itself
|
|
|
|
What is not yet durable:
|
|
- verification job history
|
|
- verification review history
|
|
- verification event history
|
|
|
|
That means frontend can integrate with verification routes now, but should not treat them as mission-critical durable state yet.
|
|
|
|
## 6) Recommended frontend environment variables
|
|
|
|
```env
|
|
CORE_API_V2_BASE_URL=https://krow-core-api-v2-e3g6witsvq-uc.a.run.app
|
|
COMMAND_API_V2_BASE_URL=https://krow-command-api-v2-e3g6witsvq-uc.a.run.app
|
|
QUERY_API_V2_BASE_URL=https://krow-query-api-v2-e3g6witsvq-uc.a.run.app
|
|
```
|
|
|
|
## 7) Service docs
|
|
|
|
- [Core API](./core-api.md)
|
|
- [Command API](./command-api.md)
|
|
- [Query API](./query-api.md)
|
|
|
|
## 8) Frontend integration rule
|
|
|
|
Do not point screens directly at database access just because a route does not exist yet.
|
|
|
|
If a screen is missing from the docs, the next step is to define the route contract and add it to `query-api-v2` or `command-api-v2`.
|