# API — Golden Rules

## Style

- REST only for public HTTP.
- Never use POST for pure queries (use GET).
- Verbs: GET / POST / PUT / DELETE.
- Prefix: `/api/v1`.

## Envelope (mandatory — never invent alternatives)

Success:

```json
{ "code": 0, "message": "success", "data": {} }
```

Error:

```json
{ "code": 10001, "message": "user not found" }
```

Forbidden shapes: `{ success: true }`, `{ ok: true }`, bare arrays as root.

## Error codes

- Start business codes at **10000**.
- 0 = success.
- Ranges: 1xxxx general/auth, 2xxxx profile, 3xxxx report/scale, 4xxxx order/membership, 5xxxx AI/companion.

## Pagination

Query: `page`, `page_size`  
Data:

```json
{ "list": [], "total": 0, "page": 1, "page_size": 20 }
```

## Auth

- Bearer token in `Authorization` header when required.
- Resource ownership checked in service layer.

## Docs

- Public route changes update `proto/openapi.yaml` in the same change set.
- Do not invent endpoints that are not in OpenAPI / task spec.