# GCS-API-001 - API and Wire Contract

Spec ID      : GCS-API-001
Title        : API and Wire
Version      : v1.0
Status       : Settled
Owner        : Phil
Approver     : Phil
Settled      : 2026-07-08
Depends on   : GCS-SYS-001, GCS-NAME-001, GCS-DATA-002, GCS-SEC-001
Supersedes   : -

## 1. Current Phase

There is no API implementation in Phase 0. The only public runtime surface is
static `index.html` plus browser-only figure scripts. Therefore:

- No route files may exist under `api/` or `app/api/`.
- No DTO/schema files may exist without a registered inventory in this
  contract.
- No code may advertise an API endpoint as implemented.

## 2. Future Wire Rules

When an API is introduced, it must obey these rules:

- Internal Python and database names use `snake_case`.
- JSON wire keys use `camelCase`.
- Serialization performs snake -> camel exactly once.
- Handlers must reject unknown request fields.
- Mutating requests require an idempotency key.
- Responses use a closed envelope:

```json
{
  "data": {},
  "error": null,
  "meta": {
    "asOfTimestamp": "2026-07-08T00:00:00Z",
    "sourceAuthorityTier": "TIER_1"
  }
}
```

## 3. Endpoint Inventory

Current inventory: none.

Introducing any endpoint requires an amendment listing:

- Route path in `kebab-case`.
- Method.
- Request DTO.
- Response DTO.
- Source authority requirements.
- Idempotency behavior.
- Positive verification test.
- Negative verification test.
- Validation command.

## 4. Static Surface Boundary

The current HTML page may link to contract files and may fetch World Bank
public data in browser-only figure code. It must not mutate local state, write
records, or present fetched data as an authoritative GCS ingestion result.

## 5. Validation

Positive verification: `python3 -m tools.check_contracts --check` passes while
no API implementation exists and static sources carry contract headers.

Negative verification: adding `api/`, `app/api/`, route-like source files, or
DTO/schema files without amending this inventory fails the gate.