# Legacy API Spec (Retraced)

This spec is based on:
- backend code in `../dewemoji-api`
- extension usage in `../dewemoji-chrome-ext`

## 1) Implemented backend API (`dewemoji-api`)

### `GET /api/emojis`
- Params supported in backend code:
  - `query` (search string)
  - `category`
  - `subcategory`
  - `page` (default `1`)
  - `limit` (default `50`, max `50`)
  - `key` (optional license key for tier detection)
- Response:
```json
{
  "items": [],
  "page": 1,
  "limit": 50,
  "total": 0
}
```
- ETag + `Cache-Control: public, max-age=300`

### `GET /api/emoji/{slug}` and `GET /api/emoji?slug=...`
- Response: single emoji object
- Not found: `404 {"error":"not_found"}`
- ETag + `Cache-Control: public, max-age=300`

### `GET /api/categories`
- Response shape:
```json
{
  "Smileys & Emotion": ["face-smiling", "face-affection"],
  "People & Body": ["hand-fingers-open", "person"]
}
```
- `Cache-Control: public, max-age=3600`

### Router-level behavior
- CORS: `*`
- Methods: `GET, OPTIONS`
- Rate-limit: ~60 req/min/IP
- Rate-limit error: `429 {"error":"rate_limited"}`

## 2) Extension-consumed API contract (`dewemoji-chrome-ext`)

Extension points to: `https://api.dewemoji.com/v1`

### `GET /v1/emojis`
- Params sent by extension:
  - `q`
  - `category`
  - `subcategory`
  - `page`
  - `limit` (Free 20 / Pro 50 in client logic)
- Expected response fields:
  - top-level: `items`, `total`
  - per-item: at least `emoji`, `name`, `category`, `subcategory`, `supports_skin_tone`
- Header read by extension: `X-Dewemoji-Tier`

### `GET /v1/categories`
Extension accepts two payload styles:
1) object map `{ "Category": ["sub"] }`
2) items array `{ "items": [{ "name": "Category", "subcategories": [...] }] }`

### `POST /v1/license/verify`
- Body sent:
```json
{
  "key": "<license>",
  "account_id": "<hashed-account-id>",
  "version": "<extension-version>"
}
```
- Expected minimum response:
```json
{ "ok": true }
```
or
```json
{ "ok": false, "error": "..." }
```

## 3) Compatibility gaps to handle in rebuild

- Accept both `q` and `query` for search.
- Keep `/v1/*` contract stable for extension.
- Return `X-Dewemoji-Tier`.
- Preserve key item fields used by extension UI and tone logic.