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 key | Context variable | Default |
|---|---|---|
api-key | openfigi.api-key | none: the API works without a key, at lower limits |
base-url | openfigi.base-url | https://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
openfigi.api-keyopenfigi.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.".