Skip to content

Commit 5aabace

Browse files
zhyupezhyupe
committed
docs: update README and add update API documentation
1 parent 0e6083f commit 5aabace

2 files changed

Lines changed: 203 additions & 34 deletions

File tree

‎README.md‎

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
## xivstrings Go API
22

3-
This Go project exposes a small HTTP API over the JSON data exported by [ixion](https://github.com/thewakingsands/ixion)'s strings export. Data is loaded from the [ixion releases](https://github.com/thewakingsands/ixion/releases): on startup the server fetches the latest release and, if needed, downloads `strings.zip`, extracts it, and builds a search index. Queries use the current version's data.
3+
This Go project exposes a small HTTP API over the JSON data exported by
4+
[ixion](https://github.com/thewakingsands/ixion)'s strings export. Data is
5+
loaded from the
6+
[ixion releases](https://github.com/thewakingsands/ixion/releases): on startup
7+
the server fetches the latest release and, if needed, downloads `strings.zip`,
8+
extracts it, and builds a search index. Queries use the current version's data.
49

510
### Building and running
611

@@ -13,7 +18,7 @@ go run .
1318
By default the server:
1419

1520
- Listens on `127.0.0.1:8080`
16-
- Uses `data/` as the root directory for app data (see below)
21+
- Uses `data/` as the root directory for app data
1722

1823
Override with flags:
1924

@@ -23,18 +28,22 @@ go run . -addr=":8090" -data="/path/to/data"
2328

2429
### Data directory layout
2530

26-
The `-data` path is the **root** for all app data. The server expects or creates:
31+
The `-data` path is the root for all app data. The server expects or creates:
2732

28-
- `data/version` — text file with the current version (e.g. `publish-20260303-8b409c8`)
29-
- `data/strings/<version>/` — extracted JSON files from `strings.zip`
30-
- `data/index/<version>/` — Bleve search index for that version
33+
- `data/version` - text file with the current version, for example `publish-20260303-8b409c8`
34+
- `data/strings/<version>/` - extracted JSON files from `strings.zip`
35+
- `data/index/<version>/` - Bleve search index for that version
3136

32-
On first run (or when the version changes), the server will fetch the latest [ixion release](https://github.com/thewakingsands/ixion/releases/latest), download `strings.zip`, extract to `data/strings/<version>/`, and build the index under `data/index/<version>/`.
37+
On first run, or when the version changes, the server fetches the latest
38+
[ixion release](https://github.com/thewakingsands/ixion/releases/latest),
39+
downloads `strings.zip`, extracts to `data/strings/<version>/`, and builds the
40+
index under `data/index/<version>/`.
3341

3442
### Version and update
3543

36-
- **GET /api/version** — returns the current data version, e.g. `{"version":"publish-20260303-8b409c8"}`.
37-
- **POST /api/version** — triggers a version check and, if the latest release differs from local, downloads and indexes the new data, then reloads the store. Requires a `token` query parameter that matches the environment variable `XIVSTRINGS_UPDATE_TOKEN`. If `XIVSTRINGS_UPDATE_TOKEN` is not set, POST returns `403` and update is not allowed.
44+
- `GET /api/version` returns the current data version and the latest update status
45+
- `POST /api/version?token=...` starts an async update job and returns `202 Accepted`
46+
- Full update API details: [docs/update-api.md](docs/update-api.md)
3847

3948
Example:
4049

@@ -43,10 +52,10 @@ Example:
4352
export XIVSTRINGS_UPDATE_TOKEN=your-secret-token
4453
go run .
4554

46-
# Query current version (no auth)
55+
# Query current version and update status
4756
curl http://127.0.0.1:8080/api/version
4857

49-
# Trigger update (with token)
58+
# Trigger async update
5059
curl -X POST "http://127.0.0.1:8080/api/version?token=your-secret-token"
5160
```
5261

@@ -68,26 +77,17 @@ Each JSON file under the strings directory contains an array of items:
6877

6978
### HTTP APIs
7079

71-
- **Search strings**
72-
73-
- **Endpoint**: `GET /api/search`
74-
- **Query parameters**:
75-
- `lang` (required): language code, e.g. `en`, `ja`, `chs`
76-
- `q` (required): substring to search for in the given language
77-
- `sheet` (optional): restrict search to a specific sheet name
78-
- `offset` (optional): offset of the first item to return (default 0)
79-
- `limit` (optional): maximum number of items to return (default 100, max 1000)
80-
- **Response**: JSON with matching items and meta (total, elapsed).
81-
82-
- **Get items by sheet**
83-
84-
- **Endpoint**: `GET /api/items`
85-
- **Query parameters**:
86-
- `sheet` (required): sheet name
87-
- `offset` (optional): offset (default 0)
88-
- `limit` (optional): max items (default 100, max 1000)
89-
- **Response**: JSON with items for the sheet and meta.
90-
91-
- **Version**
92-
- **GET /api/version**: current data version.
93-
- **POST /api/version?token=...**: run update from ixion release (requires `XIVSTRINGS_UPDATE_TOKEN`).
80+
- Search strings
81+
- Endpoint: `GET /api/search`
82+
- Query parameters: `lang` required, `q` required, `sheet` optional, `offset` optional, `limit` optional
83+
- Response: JSON with matching items and meta fields such as `total` and `elapsed`
84+
85+
- Get items by sheet
86+
- Endpoint: `GET /api/items`
87+
- Query parameters: `sheet` required, `offset` optional, `limit` optional
88+
- Response: JSON with items for the sheet and meta
89+
90+
- Version
91+
- `GET /api/version`: current data version and update status
92+
- `POST /api/version?token=...`: start async update from the latest ixion release
93+
- See [docs/update-api.md](docs/update-api.md) for the full contract

‎docs/update-api.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Update API
2+
3+
The update API lets you trigger a background refresh of the local `xivstrings`
4+
data from the latest `ixion` release, then poll for completion.
5+
6+
`POST /api/version` is asynchronous. It returns immediately with
7+
`202 Accepted`, while the server downloads `strings.zip`, rebuilds the Bleve
8+
index, and swaps the in-memory store in the background.
9+
10+
## Authentication
11+
12+
Updates are disabled unless the server is started with the
13+
`XIVSTRINGS_UPDATE_TOKEN` environment variable.
14+
15+
Clients must pass the same value as the `token` query parameter:
16+
17+
```text
18+
POST /api/version?token=your-secret-token
19+
```
20+
21+
If the token is missing or invalid, the server rejects the request.
22+
23+
## Endpoints
24+
25+
### Get current version and update status
26+
27+
`GET /api/version`
28+
29+
Returns the currently active data version and the latest update job status.
30+
31+
Example response when idle:
32+
33+
```json
34+
{
35+
"version": "publish-20260303-8b409c8",
36+
"update": {
37+
"state": "idle"
38+
}
39+
}
40+
```
41+
42+
Example response while running:
43+
44+
```json
45+
{
46+
"version": "publish-20260303-8b409c8",
47+
"update": {
48+
"state": "running",
49+
"startedAt": "2026-05-11T13:06:40Z"
50+
}
51+
}
52+
```
53+
54+
Example response after success:
55+
56+
```json
57+
{
58+
"version": "publish-20260510-deadbeef",
59+
"update": {
60+
"state": "success",
61+
"startedAt": "2026-05-11T13:06:40Z",
62+
"finishedAt": "2026-05-11T13:10:12Z",
63+
"version": "publish-20260510-deadbeef",
64+
"updated": true
65+
}
66+
}
67+
```
68+
69+
Example response after a no-op check:
70+
71+
```json
72+
{
73+
"version": "publish-20260510-deadbeef",
74+
"update": {
75+
"state": "success",
76+
"startedAt": "2026-05-11T13:20:00Z",
77+
"finishedAt": "2026-05-11T13:20:01Z",
78+
"version": "publish-20260510-deadbeef",
79+
"updated": false
80+
}
81+
}
82+
```
83+
84+
Example response after failure:
85+
86+
```json
87+
{
88+
"version": "publish-20260303-8b409c8",
89+
"update": {
90+
"state": "error",
91+
"startedAt": "2026-05-11T13:06:40Z",
92+
"finishedAt": "2026-05-11T13:07:05Z",
93+
"error": "fetch latest release: github api status 403: rate limit exceeded"
94+
}
95+
}
96+
```
97+
98+
### Trigger an update
99+
100+
`POST /api/version?token=...`
101+
102+
Starts an update job if one is not already running.
103+
104+
Example response when a new job starts:
105+
106+
```json
107+
{
108+
"message": "update started",
109+
"update": {
110+
"state": "running",
111+
"startedAt": "2026-05-11T13:06:40Z"
112+
}
113+
}
114+
```
115+
116+
Example response when a job is already running:
117+
118+
```json
119+
{
120+
"message": "update already in progress",
121+
"update": {
122+
"state": "running",
123+
"startedAt": "2026-05-11T13:06:40Z"
124+
}
125+
}
126+
```
127+
128+
## Update status fields
129+
130+
The `update` object can contain these fields:
131+
132+
- `state`: one of `idle`, `running`, `success`, or `error`
133+
- `startedAt`: UTC timestamp in RFC 3339 format
134+
- `finishedAt`: UTC timestamp in RFC 3339 format
135+
- `version`: release version detected by the completed update job
136+
- `updated`: `true` if a new version was downloaded and loaded, `false` if the latest version was already present
137+
- `error`: failure message for `state = "error"`
138+
139+
## Typical client flow
140+
141+
1. Call `POST /api/version?token=...`.
142+
2. If the server returns `202`, start polling `GET /api/version`.
143+
3. Continue polling while `update.state` is `running`.
144+
4. Stop when `update.state` becomes `success` or `error`.
145+
5. Read `update.updated` to determine whether a new version was actually applied.
146+
147+
## Status codes
148+
149+
- `200 OK`: returned by `GET /api/version`
150+
- `202 Accepted`: returned by `POST /api/version` when the request is accepted
151+
- `400 Bad Request`: missing `token`
152+
- `401 Unauthorized`: invalid `token`
153+
- `403 Forbidden`: updates are disabled because `XIVSTRINGS_UPDATE_TOKEN` is not configured
154+
- `405 Method Not Allowed`: unsupported HTTP method
155+
- `500 Internal Server Error`: unexpected server-side error while reading the current version
156+
157+
## Curl examples
158+
159+
```bash
160+
curl http://127.0.0.1:8080/api/version
161+
```
162+
163+
```bash
164+
curl -X POST "http://127.0.0.1:8080/api/version?token=your-secret-token"
165+
```
166+
167+
```bash
168+
watch -n 5 'curl -s http://127.0.0.1:8080/api/version'
169+
```

0 commit comments

Comments
 (0)