Skip to content

Latest commit

 

History

History
77 lines (57 loc) · 2.99 KB

README.md

File metadata and controls

77 lines (57 loc) · 2.99 KB

API overview

Every endpoint is a GET. Nothing here writes anything, so nothing you send can break state. Responses are JSON except pronunciation audio.

Endpoints

Endpoint Purpose Docs
/v1/word/:word Look a word up Word lookup
/v1/word/:word/:source Look it up in one provider Word lookup
/v2/word/:word Same, richer shape Versions
/v2/word/:word/:source Same, one provider Versions
/v1/tts/:word Pronunciation audio Pronunciation
/v1/search Full-text search over cached entries Search
/v1/conjugate/:verb Conjugate a verb Conjugation
/v1/pluralize/:noun Pluralise a noun Pluralization
/v1/audio/:word Forvo audio (needs a key) Pronunciation
/v1/sources Which providers exist and their health Sources endpoint
/v1/healthz Liveness Health
/openapi.json Machine-readable API description below
/docs Interactive reference below

/docs and /openapi.json

/openapi.json is an OpenAPI document: a standard JSON description of every endpoint, parameter and response. Tools read it to generate client libraries, populate Postman, or drive tests.

/docs renders that document as a browsable page. Expand an endpoint, fill in a parameter, press the button, see the real response.

You do not need either to use this API, curl works fine, but /docs is the fastest way to see what a parameter is called.

Both are generated from the code, so they cannot drift out of date. A test asserts every mounted route appears in the document.

Response shape

Word lookups always return this envelope:

{
  "headword": "casă",
  "entries": [ … ],
  "cache":  { "hits": 8, "misses": 0 },
  "errors": [ … ]
}
  • entries: the results. Possibly empty.
  • cache: how many entries came from cache vs a fresh fetch. Useful for understanding latency; ignorable otherwise.
  • errors: providers that failed. This is normally empty. A non-empty errors with a non-empty entries means some sources worked and some did not: the response is still usable. See Errors.

One slow or broken dictionary never fails the whole request.

Input rules

Words are validated before anything else happens. A word must be:

  • 1–64 characters
  • letters, combining marks, spaces, - and ' only

Anything else gets 400 INVALID_INPUT. This is why /v1/word/<script> is rejected rather than processed.

Percent-encode diacritics if your tooling needs it: cas%C4%83 is casă.

Rate limiting

The API rate-limits itself against upstream dictionaries so it stays a polite client, see Rate limits & robots. There is also an inbound limit (RATE_LIMIT_PER_MIN, default 60/min per client).