80 lines
1.1 KiB
Markdown
80 lines
1.1 KiB
Markdown
# API Response Rules
|
|
|
|
All API responses must be stable and implementation-friendly.
|
|
|
|
## Success Envelope
|
|
|
|
For single resources:
|
|
|
|
```json
|
|
{
|
|
"data": {},
|
|
"meta": {}
|
|
}
|
|
```
|
|
|
|
For lists:
|
|
|
|
```json
|
|
{
|
|
"data": [],
|
|
"meta": {
|
|
"count": 0,
|
|
"limit": 50,
|
|
"offset": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Envelope
|
|
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "VALIDATION_ERROR",
|
|
"message": "Human readable message",
|
|
"details": {},
|
|
"trace_id": "optional"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Required Resource Fields
|
|
|
|
Most persisted resources should include:
|
|
|
|
- `id`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
Geospatial resources should also include:
|
|
|
|
- `crs`
|
|
- `bounds`
|
|
- `geometry_type` where applicable
|
|
|
|
Analysis resources should include:
|
|
|
|
- `status`
|
|
- `parameters`
|
|
- `outputs`
|
|
- `metrics`
|
|
- `error_message` when failed
|
|
|
|
## Pagination
|
|
|
|
Use `limit` and `offset` for V1. Cursor pagination can be added later if needed.
|
|
|
|
## Sorting
|
|
|
|
Default sort: newest first for projects, datasets, analyses and exports.
|
|
|
|
## Contract Drift Rule
|
|
|
|
If implementation changes any response shape, update:
|
|
|
|
- `contracts/api/`
|
|
- API docs
|
|
- frontend API client types
|
|
- tests
|