[Feature] Add public REST API for aggregated company stats

[necdetsanli]

Summary

Implement a public REST API so third parties can fetch Do Not Ghost Me data programmatically (primarily aggregated statistics, with carefully scoped access, rate limits, and privacy safeguards).

Motivation / use case

• Researchers / journalists / community tools can analyze trends and build dashboards.
• Candidates can use alternative clients (CLI/mobile) without scraping HTML.
• Self-hosters can integrate their instance with other systems.
• Reduces pressure to expose raw reports publicly if we provide a safe aggregated API.

Proposed solution

API scope (MVP: aggregated-only)

• Provide read-only endpoints that expose aggregated stats rather than raw user submissions:
  • GET /api/v1/companies
    • List companies with report counts + optional filters (country, stage, jobLevel, category)
    • Supports pagination + stable sorting
  • GET /api/v1/companies/{companyId}
    • Company detail: totals + breakdowns (stage/job level/category)
  • GET /api/v1/stats/overview
    • Global totals, last-7-days count, top reported (time window)
  • GET /api/v1/meta/enums
    • Enum values + labels/slugs for clients (stage/job level/category/countries)

Versioning

• Prefix with /api/v1/... for explicit versioning.
• Document deprecation rules in README.

Filtering / pagination

• Cursor-based pagination preferred (stable under inserts).
• Query params for filters:
  • country=TR
  • stage=TECHNICAL
  • jobLevel=JUNIOR
  • category=ENGINEERING
  • q= for company name search (normalized).

Rate limiting

• Add API-specific limits (separate from report submission limits):
  • per IP/day or per token (if we add API keys).
• Consider ETag/Cache-Control for GET endpoints to reduce load.

Authentication (optional)
Two modes:

1. Public, rate-limited (simplest MVP)
2. API keys for higher quotas / partner access
   • admin-generated keys
   • scoped permissions (read-only), with revocation

Privacy & safety

• Default API should NOT expose:
  • raw reports
  • timestamps granular enough to re-identify
  • anything tied to rate-limit tables or IP-derived data
• If we later add “raw reports” API:
  • it must be heavily redacted, paginated, and include moderation state
  • likely requires additional policy + anti-defamation guardrails

Documentation

• Add /api-docs (static page) or a docs/api.md.
• Provide examples (curl) and response schemas.
• Optional: OpenAPI spec (openapi.yaml) generated/maintained manually.

Alternatives considered

• GraphQL only (more complex to secure/costly to operate for now).
• “Export CSV” only (less flexible, still useful later).
• Encourage scraping (not ideal; breaks and adds load).

Which part(s) of the project does this touch?

• Report form / submission flow
• Rate limiting / abuse protection
• Top companies listing & filters
• Admin dashboard / moderation
• Privacy / logging / config
• Documentation & developer experience
• Other / unsure

Database schema changes?

Maybe

API contract changes?

Yes

Existing user behaviour changes?

No

If Yes/Maybe, describe briefly

• Adds new public endpoints with a stable contract.
• Might require new DB indexes/materialized views for performance at scale.

Additional context

• API should mirror UI semantics (same enum labels/slugs, same aggregation rules).
• Strong preference for “aggregated-first” to keep privacy risk low.