geointel/docs/13-implementation-traps/API_RESPONSE_RULES.md

API Response Rules

All API responses must be stable and implementation-friendly.

Success Envelope

For single resources:

{
  "data": {},
  "meta": {}
}

For lists:

{
  "data": [],
  "meta": {
    "count": 0,
    "limit": 50,
    "offset": 0
  }
}

Error Envelope

{
  "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