dewemoji/legacy-api-spec.md

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:

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

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

{
  "key": "<license>",
  "account_id": "<hashed-account-id>",
  "version": "<extension-version>"
}

• Expected minimum response:

{ "ok": true }

or

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