Shared transport for the OpenFIGI API: the settings resolver (per-call opts first, then context variables, then defaults), a typed HttpError, and the JSON request helper.

opts keyContext variableDefault
api-keyopenfigi.api-keynone: the API works without a key, at lower limits
base-urlopenfigi.base-urlhttps://api.openfigi.com/v3

Per-call credentials. An api-key in opts is masked in call records and never written to context. Present but blank or null, it is an error, never a fallback to context. A per-call base-url only ever gets the per-call api-key: the context key is never sent to a per-call URL, and without a per-call key the request goes unkeyed.

Context Vars

Optional
  • openfigi.api-key
  • openfigi.base-url

Values

BASE_URL

BASE_URL: Str "https://api.openfigi.com/v3"

KEY_HEADER

KEY_HEADER: Str "X-OPENFIGI-APIKEY"

LIMITS

LIMITS: Map {
  keyed: {
    jobs-per-request: 100,
    mapping-per-minute: 250,
    search-per-minute: 20
  },
  anonymous: {
    jobs-per-request: 10,
    mapping-per-minute: 25,
    search-per-minute: 5
  }
}

OpenFIGI's published limits, per 60-second window, per key (or per IP without one). jobs-per-request caps one /mapping call; mapping-per-minute counts /mapping and /mapping/values calls; search-per-minute counts /search and /filter calls.

PACKAGE_AGENT

PACKAGE_AGENT: Str "hot-dev-openfigi-pkg/0.1 (+https://hot.dev)"

Functions

auth-headers

fn (cfg: Map): Map

{X-OPENFIGI-APIKEY: key} when resolved settings carry a key, else {} (pure).

Example

// With a key the Map holds X-OPENFIGI-APIKEY. Without one it is empty.
::openfigi::api/auth-headers({api-key: null})  // {}

given

fn (v: Any): Bool

True for a non-null value that is not a blank string.

Example

::openfigi::api/given("IBM")  // true
::openfigi::api/given("  ")  // false
::openfigi::api/given(null)  // false

http-error

fn (response: ::hot::http/HttpResponse, url: Str): HttpError

Build an HttpError from a non-2xx response. Exposed for testing; every request uses it.

Example

url "https://api.openfigi.com/v3/search"
response ::hot::http/HttpResponse({status: 429, headers: {"retry-after": "7"}, body: "Rate limit reached."})
e ::openfigi::api/http-error(response, url)
e.retry-after  // 7
e.message  // "openfigi: HTTP 429: Rate limit reached."

path-segment

fn (value: Any): Str

Percent-encode one path segment.

Example

::openfigi::api/path-segment("a b")  // "a%20b"

request

fn (cfg: Map, method: Str, path: Str, body: Any): Any

Send method to ${cfg.base-url}${path} and return the decoded JSON body on 2xx, or an Err carrying HttpError. A non-null body is sent as JSON. A transport failure passes through as its own Err.

Example

::api ::openfigi::api

cfg ::api/resolve({})
out ::api/request(cfg, "GET", "/mapping/values/idType", null)
out.values

resolve

fn (opts: Map): Map

Resolve settings for one call: {api-key, base-url, limits}, where limits is LIMITS.keyed or LIMITS.anonymous. Values in opts win over context. An Err when api-key is in opts but blank or null.

Example

cfg ::openfigi::api/resolve({api-key: ::hot::ctx/get("tenant.figi-key")})
cfg.limits.jobs-per-request   // 100

Types

HttpError

HttpError type {
    status: Int,
    url: Str,
    headers: Map,
    body: Any,
    retry-after: Int?,
    message: Str
}

A non-2xx OpenFIGI response. url is the requested URL (the key goes in a header, never the URL); retry-after the seconds until the rate limit window resets on 429s (from Retry-After or ratelimit-reset); message a one-line summary that never includes the key. OpenFIGI's error bodies are short text, e.g. "Invalid API key." or "Request may only contain 10 mapping jobs.".