import type { Metadata } from 'next';
import Link from 'next/link';
import { PageHeader, Section, Note } from '@/components/ui/section';
import { SITE_URL } from '@/lib/site';

export const metadata: Metadata = { title: 'Developers', description: 'CancerIndex public API: envelope, rate limits, examples and OpenAPI docs.' };

export default function DevelopersPage() {
  return (
    <div className="ci-prose max-w-3xl">
      <PageHeader kicker="Developers" title="Public API" lede="Everything on the site is available as JSON under /api/v1, served by the CancerIndex API service and proxied through this host. Identifiers are stable; every response names its sources." />
      <Section id="docs" kicker="Reference" title="OpenAPI documentation">
        <p>
          Interactive documentation is served by the API at{' '}
          <a className="ci-link" href="/api/v1/docs">
            /api/v1/docs
          </a>
          . Base URL: <code>{SITE_URL}/api/v1</code>.
        </p>
      </Section>
      <Section id="envelope" kicker="Format" title="Response envelope">
        <p>Every successful response wraps its payload with the sources that contributed and the data release, so attribution travels with the data:</p>
        <pre className="ci-code">{`{
  "data": { ... } | [ ... ],
  "sources": [ { "slug": "oncotree", "name": "OncoTree", "license": "CC BY 4.0", "retrievedAt": "2026-09-08T09:07:07Z" } ],
  "dataRelease": "2026-09-08",
  "meta": { "page": 1, "pageSize": 50, "total": 865 }   // on paginated endpoints
}`}</pre>
        <p>Errors return <code>{`{ "error": { "code": "not_found", "message": "…" } }`}</code> with the matching HTTP status.</p>
      </Section>
      <Section id="limits" kicker="Fair use" title="Rate limits">
        <ul>
          <li>Anonymous: 60 requests per minute per IP.</li>
          <li>
            With an API key (<code>Authorization: Bearer …</code>): per-key limit according to tier (free 60/min, research and institutional tiers on request).
          </li>
          <li>
            Responses include <code>X-RateLimit-Limit</code>, <code>X-RateLimit-Remaining</code> and <code>Retry-After</code> on 429.
          </li>
        </ul>
      </Section>
      <Section id="examples" kicker="Examples" title="curl">
        <pre className="ci-code">{`# One cancer entity with codes, aliases and counters
curl -s ${SITE_URL}/api/v1/cancers/diffuse-glioma | jq .

# Search across entities
curl -s "${SITE_URL}/api/v1/search?q=glioma" | jq '.data[] | {type, title}'

# Current ranking snapshot for a metric and scope
curl -s "${SITE_URL}/api/v1/rankings/active_trials?scope=geo=WORLD|sex=all|age=all|year=latest|level=top" | jq .

# Same ranking as CSV with attribution rows (served by the web app)
curl -sL "${SITE_URL}/api/export/rankings.csv?metric=active_trials" -o active_trials.csv`}</pre>
      </Section>
      <Section id="identifiers" kicker="Identifiers" title="Stable identifiers">
        <p>
          Public IDs look like <code>CI-CAN-00000123</code> (cancer), <code>CI-GENE-…</code>, <code>CI-VAR-…</code>, <code>CI-DRUG-…</code>, <code>CI-TRIAL-…</code>, <code>CI-PUB-…</code>, <code>CI-SOURCE-…</code>. They are minted once and never reused; merged entities redirect to the surviving record. Upstream identifiers (NCIt, OncoTree, ICD-10, DOID, HGNC, NCT, PMID) are returned alongside with their match type.
        </p>
      </Section>
      <Note>
        Terms: attribution required (see <Link className="ci-link" href="/data">Data</Link>); no medical advice; respect the upstream licenses listed on each <Link className="ci-link" href="/sources">source</Link>.
      </Note>
    </div>
  );
}