diff --git a/.prettierignore b/.prettierignore index d84754c..d3f5478 100644 --- a/.prettierignore +++ b/.prettierignore @@ -26,3 +26,4 @@ TODO.complete/ # preview deck) stay hand-wrapped — prettier-ignore corrupts files. src/pages/compare.astro src/pages/maps/\[systemCode\].astro +src/pages/api-docs.astro diff --git a/src/layouts/Base.astro b/src/layouts/Base.astro index 2da00b9..f388bc2 100644 --- a/src/layouts/Base.astro +++ b/src/layouts/Base.astro @@ -45,7 +45,7 @@ const navItems: NavItem[] = [ label: "Developers", children: [ { href: "/api", label: "API playground" }, - { href: "/api-docs", label: "API reference" }, + { href: "https://api.interscript.org/docs", label: "API reference" }, { href: "/status", label: "Status" }, ], }, @@ -87,7 +87,7 @@ const drawerGroups: Array<{ label: string; links: NavLink[] }> = [ label: "Developers", links: [ { href: "/api", label: "API playground" }, - { href: "/api-docs", label: "API reference" }, + { href: "https://api.interscript.org/docs", label: "API reference" }, { href: "/status", label: "Status" }, ], }, diff --git a/src/pages/api-docs.astro b/src/pages/api-docs.astro index 795190e..b7fa84b 100644 --- a/src/pages/api-docs.astro +++ b/src/pages/api-docs.astro @@ -1,451 +1,16 @@ --- +// The API reference is deployed content of api.interscript.org itself. import Base from "../layouts/Base.astro" --- - -
-
-

API reference

-

Three endpoints. Real documentation.

-

- The Interscript REST API runs at https://interscript.org/api. Open source, no - auth, no rate limits (yet). Browse the OpenAPI 3.1 spec below or download it from /openapi.json. -

-
- ↓ OpenAPI 3.1 JSON - Postman collection ↗ -
-
-
- -
- - -
-
- POST - /api/transliterate -
-

- Transliterate a single string. Use POST when the input is large, contains newlines, or you - prefer explicit request bodies. -

- -

Request body

-
- -

Response — 200 OK

-
- -

cURL

-
- -

JavaScript (browser / Node 18+)

-
- -

Ruby

- 
 "application/json",
-)
-puts JSON.parse(res.body)["output"]  # → "Anton"`} />
-
- -
-
- GET - /api/transliterate -
-

- Same operation, query-string form. Easier to test in a browser or one-liner curl. Avoid for - inputs containing newlines. -

- -

Query parameters

- - - - - - - - - -
NameRequiredDescription
systemyesInterscript system code
inputyesSource text (≤ 10,000 chars)
stagenoStage to execute (default main)
- -

cURL

- 
curl -G 'https://interscript.org/api/transliterate' \\
-  --data-urlencode 'system=bgnpcgn-ukr-Cyrl-Latn-2019' \\
-  --data-urlencode 'input=Антон'
-
- -
-
- GET - /api/systems -
-

- List every transliteration system in the catalogue. Optional filters by authority or script. -

- -

Query parameters

- - - - - - - - - -
NameRequiredDescription
authoritynoAuthority slug (bgnpcgn, iso, …)
source_scriptnoISO 15924 source code (Cyrl, Arab, …)
destination_scriptnoISO 15924 destination code
- -

Example response (truncated)

-
-
- -
-
- GET - /api/detect -
-

- Given a source-script input and an observed romanization, returns the candidate systems in - the relevant script family. Pair with the detection playground for full - ranking. -

- -

Query parameters

- - - - - - - - - -
NameRequiredDescription
inputyesSource text
outputyesObserved romanization
source_scriptnoNarrow the candidate set
-
- -
-

Schemas

-

- Response shapes (subset shown — see full spec for components/schemas/*). -

- -

TransliterationResult

-
-
- -
-

Limits & fairness

-
    -
  • Input size: 10,000 chars per request.
    • -
  • Auth: none. CORS open to all origins.
    • -
  • - Rate limits: currently none. If abused, will add a per-IP cap with 429 responses - and Retry-After headers. -
    • -
  • - Uptime: best-effort. For production pipelines, run interscript-ts locally — same engine, same byte-for-byte output. -
    • -
  • - Privacy: no logging of input content. Aggregate request counts only. -
    • -
-
+ +
+

API reference

+ +

The API reference now lives at api.interscript.org/docs.

- + diff --git a/src/pages/contributing.astro b/src/pages/contributing.astro index c1c5ef5..e84f24c 100644 --- a/src/pages/contributing.astro +++ b/src/pages/contributing.astro @@ -127,7 +127,7 @@ stage main {
  • Available in the Ruby gem (next release)
  • Available in interscript-ts via the ISC runtime
  • Live on interscript.org (next site build)
    • -
  • Available through the REST API
    • +
  • Available through the REST API
    • diff --git a/test/new-features.test.ts b/test/new-features.test.ts index a4f685d..0722602 100644 --- a/test/new-features.test.ts +++ b/test/new-features.test.ts @@ -166,7 +166,7 @@ describe("navigation across new pages", () => { "/scripts", "/use-cases", "/api", - "/api-docs", + "https://api.interscript.org/docs", "/status", "/authorities", "/contributing", diff --git a/test/redesign.test.ts b/test/redesign.test.ts index b051a07..236f9c1 100644 --- a/test/redesign.test.ts +++ b/test/redesign.test.ts @@ -189,7 +189,7 @@ describe("navigation and chrome", () => { "/scripts", "/use-cases", "/api", - "/api-docs", + "https://api.interscript.org/docs", "/status", "/authorities", "/contributing", diff --git a/test/round3-features.test.ts b/test/round3-features.test.ts index c512383..3700292 100644 --- a/test/round3-features.test.ts +++ b/test/round3-features.test.ts @@ -107,7 +107,7 @@ describe("expanded navigation across new pages", () => { "/scripts", "/use-cases", "/api", - "/api-docs", + "https://api.interscript.org/docs", "/status", "/authorities", "/contributing", diff --git a/test/round5-features.test.ts b/test/round5-features.test.ts index 995582a..e810aef 100644 --- a/test/round5-features.test.ts +++ b/test/round5-features.test.ts @@ -44,28 +44,11 @@ describe("OpenAPI spec at /openapi.json", () => { }) }) -describe("/api-docs interactive reference", () => { +describe("/api-docs redirect", () => { const html = readHtml("api-docs/index.html") - it("documents all 4 endpoints", () => { - expect(html).toContain("POST /transliterate") - expect(html).toContain("GET /transliterate") - expect(html).toContain("GET /systems") - expect(html).toContain("GET /detect") - }) - - it("includes cURL + JavaScript + Ruby examples", () => { - expect(html).toContain("curl -X POST") - expect(html).toContain("await fetch") - expect(html).toContain("Net::HTTP") - }) - - it("links to the OpenAPI JSON spec", () => { - expect(html).toContain('href="/openapi.json"') - }) - - it("documents the 10,000 char input limit", () => { - expect(html).toContain("10,000") + it("redirects to the API's self-hosted docs", () => { + expect(html).toContain("https://api.interscript.org/docs") }) }) diff --git a/test/site.test.ts b/test/site.test.ts index 8e05cfa..64f0ec5 100644 --- a/test/site.test.ts +++ b/test/site.test.ts @@ -143,7 +143,7 @@ describe("navigation", () => { "/scripts", "/use-cases", "/api", - "/api-docs", + "https://api.interscript.org/docs", "/status", "/authorities", "/contributing",