Skip to content

endpoints.md

Latest commit

 

History

History
113 lines (82 loc) · 3.22 KB

endpoints.md

File metadata and controls

113 lines (82 loc) · 3.22 KB

API — Contratos dos Endpoints

Base URL (produção): https://api.gitwidgets.dev (não deployado ainda)
Base URL (local): http://localhost:8787

Convenções Gerais

  • Todos os endpoints de widget retornam Content-Type: image/svg+xml
  • Nunca retornam JSON — mesmo em erro, retornam um SVG de erro
  • Headers de cache presentes em todas as respostas
  • Query params não reconhecidos são ignorados (não causam erro)

Headers de Resposta

Header Valores Significado
Cache-Control public, s-maxage=N, stale-while-revalidate=M TTL para CDN
X-GitWidgets-Cache HIT | MISS Se o SVG veio do KV cache
X-GitWidgets-Stale true SVG servido é expirado (upstream falhou)

Endpoints

GET /health

Status: ✅ implementado

Response: 200 OK
Body: { "status": "ok" }

GET /api/stats.svg

Status: ✅ implementado
TTL: 86400s (1d) | SWR: 172800s (2d)

Query params:
  username*     string          GitHub username (obrigatório)
  theme         string          'dark' (default) | 'light' | 'glass' | 'minimal'
  tz            IANA timezone   'UTC' (default) | 'America/Sao_Paulo' | ...
  hide          string[]        items a esconder: 'stars','commits','prs','issues','contribs'
  show_icons    boolean         'true' | 'false' (default: 'true')
  include_all_commits boolean  'true' | 'false' (default: 'false')
  locale        string          'en' (default) | 'pt' | ...

Exemplo:
  /api/stats.svg?username=torvalds&theme=dark&hide=contribs&show_icons=true

GET /api/streak.svg

Status: ❌ pendente (Phase 3)
TTL: 43200s (12h) | SWR: 86400s (1d)

Query params:
  username*     string          GitHub username (obrigatório)
  theme         string          'dark' (default) | 'light' | 'glass' | 'minimal'
  tz            IANA timezone   'UTC' (default) — afeta cálculo de "hoje"

Exemplo:
  /api/streak.svg?username=torvalds&theme=dark&tz=America/Sao_Paulo

GET /api/summary.svg

Status: ❌ pendente (Phase 5)
TTL: 518400s (6d) | SWR: 1036800s (12d)

Query params:
  username*     string     GitHub username (obrigatório)
  theme         string     'dark' (default) | ...
  langs_count   number     quantidade de linguagens a exibir (default: 5, max: 10)
  exclude_langs string[]   linguagens a excluir: 'HTML,CSS'
  layout        string     'compact' | 'default'

GET /api/activity.svg

Status: ❌ pendente (pós-MVP)
TTL: 43200s (12h) | SWR: 86400s (1d)

Query params:
  username*  string   GitHub username (obrigatório)
  theme      string   'dark' (default) | ...
  area       boolean  gráfico de área ou apenas linha
  hide_border boolean excluir borda do card

Códigos de Erro (SVG)

Todos os erros retornam 200 OK com body SVG (para não quebrar <img> em READMEs).

Cenário Mensagem no SVG TTL
Username inválido "Invalid username" 600s
Usuário não encontrado "User not found" 600s
Rate limit esgotado "Too many requests — try again later" 600s
Upstream GitHub indisponível "GitHub API unavailable — showing cached data" 600s
Erro interno "Something went wrong — please try again" 600s