122 lines
2.7 KiB
Markdown
122 lines
2.7 KiB
Markdown
# API Contract
|
|
|
|
The machine-readable OpenAPI draft is in `schemas/openapi.yaml`.
|
|
|
|
## Core endpoints
|
|
|
|
### Create trip
|
|
|
|
`POST /v1/trips`
|
|
|
|
Creates a trip shell from user inputs.
|
|
|
|
### Plan route
|
|
|
|
`POST /v1/routes/plan`
|
|
|
|
Input:
|
|
|
|
- start/end/imported GPX,
|
|
- profile,
|
|
- constraints,
|
|
- preferred providers.
|
|
|
|
Output:
|
|
|
|
- route id,
|
|
- geometry,
|
|
- distance/elevation,
|
|
- scores,
|
|
- warnings,
|
|
- candidate alternatives.
|
|
|
|
### Plan stages
|
|
|
|
`POST /v1/stages/plan`
|
|
|
|
Input:
|
|
|
|
- route id,
|
|
- day count/date range,
|
|
- daily constraints,
|
|
- sleep preferences.
|
|
|
|
Output:
|
|
|
|
- stage cards,
|
|
- Plan A/B endpoints,
|
|
- sleep/food/water/repair/bailout candidates,
|
|
- stage warnings.
|
|
|
|
### Corridor POIs
|
|
|
|
`GET /v1/routes/{route_id}/pois?category=water&buffer_km=5`
|
|
|
|
Returns route-relevant POIs with distance along route, detour distance, confidence, and source.
|
|
|
|
### Critical gaps
|
|
|
|
`GET /v1/routes/{route_id}/gaps`
|
|
|
|
Returns computed gaps for water, food, sleep, repair, bailout, and charging.
|
|
|
|
### Rule cards
|
|
|
|
`GET /v1/rules?bbox=minLon,minLat,maxLon,maxLat&route_id=...`
|
|
|
|
Returns route- or area-specific advisory cards.
|
|
|
|
### Offline pack
|
|
|
|
`POST /v1/offline-packs`
|
|
|
|
Generates a manifest and download URLs for cached trip data.
|
|
|
|
### Export
|
|
|
|
`GET /v1/routes/{route_id}/export?format=gpx`
|
|
|
|
MVP: GPX. Later: TCX and FIT.
|
|
|
|
### Local report
|
|
|
|
`POST /v1/reports`
|
|
|
|
Submits a dated, location-bound structured report. The MVP response includes `moderationStatus`, `trustScore`, and `queuedOffline` when an offline client id is supplied.
|
|
|
|
### Report sync
|
|
|
|
`POST /v1/reports/sync`
|
|
|
|
Future endpoint. The current MVP queues reports client-side while offline and resubmits them through `POST /v1/reports`.
|
|
|
|
## Error handling
|
|
|
|
Errors should include:
|
|
|
|
- machine-readable code,
|
|
- human-readable message,
|
|
- remediation suggestion,
|
|
- provider/source if relevant.
|
|
|
|
Example:
|
|
|
|
```json
|
|
{
|
|
"error": "PROVIDER_UNAVAILABLE",
|
|
"message": "routing provider \"openrouteservice\" is not available in this MVP runtime. Set ROUTING_PROVIDER=mock for fixture mode or configure the selected provider adapter and credentials.",
|
|
"details": {
|
|
"providerName": "openrouteservice",
|
|
"providerType": "routing",
|
|
"setupHint": "Set ROUTING_PROVIDER=mock for fixture mode or configure the selected provider adapter and credentials."
|
|
}
|
|
}
|
|
```
|
|
|
|
## Current MVP notes
|
|
|
|
- `schemas/openapi.yaml` reflects implemented response fields including route segments, surface breakdown, attribution, stage POI buckets, offline manifest metadata, and report queue ids.
|
|
- `format=gpx` is implemented. TCX/FIT are reserved for future `DeviceExportProvider` adapters.
|
|
- Mock providers are deterministic and require no external keys.
|
|
- Rule cards and access/protected-area warnings are advisory and confidence-scored.
|