# Static API

Yo Shabdakosh ships a static JSON API that works on GitHub Pages, raw GitHub URLs, CDNs, and any static file host.

There is no server-side search endpoint. Instead, clients fetch small index files, locate the relevant chunk, and filter JSON in the browser or app.

## Base URL

When published with GitHub Pages:

```text
https://shubhamnpk.github.io/yoshabdakosh/api/v1/
```

For local development:

```text
http://localhost:8000/api/v1/
```

## Endpoints

| Endpoint | Description |
| --- | --- |
| `metadata.json` | API version, dataset stats, endpoint list, and notes. |
| `manifest.json` | List of paginated dictionary chunks. |
| `letters.json` | Small first-letter index with counts and word-index paths. |
| `words-by-letter/अ.json` | Word-to-chunk lookup index for one starting letter. |
| `words.json` | Lightweight word-to-chunk index. |
| `sample.json` | One sample dictionary entry. |
| `chunks/0000.json` | Chunked dictionary entries, 1,000 entries per file. |

## Fetch Metadata

```js
const baseUrl = "https://shubhamnpk.github.io/yoshabdakosh/api/v1";
const metadata = await fetch(`${baseUrl}/metadata.json`).then((response) => response.json());

console.log(metadata.stats.entries);
```

## Lookup A Word

```js
const baseUrl = "https://shubhamnpk.github.io/yoshabdakosh/api/v1";
const query = "अ".normalize("NFC");
const firstLetter = Array.from(query)[0];

const letterIndex = await fetch(`${baseUrl}/letters.json`).then((response) => response.json());
const letterGroup = letterIndex.letters.find((item) => item.letter === firstLetter);

if (letterGroup) {
  const wordIndex = await fetch(`${baseUrl}/${encodeURI(letterGroup.path)}`).then((response) => response.json());
  const match = wordIndex.words.find((item) => item.word === query);

  if (match) {
    const chunk = await fetch(`${baseUrl}/${match.path}`).then((response) => response.json());
    const entry = chunk.entries.find((item) => item.word === query);
    console.log(entry);
  }
}
```

This avoids loading the full `words.json` index. Most clients should use this letter-index flow.

## Browse Chunks

```js
const baseUrl = "https://shubhamnpk.github.io/yoshabdakosh/api/v1";
const manifest = await fetch(`${baseUrl}/manifest.json`).then((response) => response.json());

for (const chunkInfo of manifest.chunks.slice(0, 3)) {
  const chunk = await fetch(`${baseUrl}/${chunkInfo.path}`).then((response) => response.json());
  console.log(chunk.firstWord, chunk.lastWord, chunk.count);
}
```

## Response Shapes

### Dictionary Entry

```json
{
  "word": "अ",
  "definitions": [
    {
      "grammar": "ना.",
      "etymology": "[सं.]",
      "senses": [
        "१. संस्कृत एकाक्षरी कोशअनुसार मूलतः विष्णुलाई जनाउने मङ्गलवाची शब्द।"
      ]
    }
  ]
}
```

### Word Index Item

```json
{
  "word": "अ",
  "index": 0,
  "chunk": 0,
  "path": "chunks/0000.json"
}
```

### Letter Index Item

```json
{
  "letter": "अ",
  "path": "words-by-letter/अ.json",
  "count": 9000,
  "startIndex": 0,
  "endIndex": 8999,
  "startChunk": 0,
  "endChunk": 8,
  "firstWord": "अ",
  "lastWord": "आ..."
}
```

## Generate API Files

After changing `data/sabdakosh.json`, regenerate the static API:

```bash
node scripts/generate-api.mjs
node scripts/validate-data.mjs
```