The complete Discourse API (strongly typed).
Copyright (c) 2023 by Gadi Cohen. MIT Licensed.
import Discourse from "discourse2";
const discourse = new Discourse("https://forums.kiri.art", {
"Api-Key": process.env.DISCOURSE_API_KEY,
"Api-Username": process.env.DISCOURSE_API_USERNAME,
});
const result = await discourse.listLatestTopics();
console.log(result);
-
You can discover the API through TypeScript text completion, or at https://docs.discourse.org/.
-
Some endpoints (like
listLatestTopics
) require auth headers in their OpenAPI spec, but not in practice (provided the requested resource is a publicly visible one). For this reason, if auth headers are required (by spec) but not provided, we'll try the call anyway and let the endpoint decide. -
Currently, the response is not validated, because unfortunately, the returned data often does not validate against the OpenAPI schema (
additionalProperties
, missingrequired
props, wrong types).I'm still deciding what to do with about this, feedback (in an issue) would be greatly appreciated. In theory I'd like to make this a configurable option, but if we don't validate, we really should be returning the data as an
unknown
type so the user performs their own validation, which is a pain, and you'll lose typescript completion. However, on the flip side, what we do now is return a type that is wrong, and TypeScript won't warn about missing (but now required) checks. -
Installed Discourse extensions / plugins may affect the result! It can add additional properties, etc. Likewise, running older versions of Discourse may return data that doesn't match the current spec.
- Validation (params; re response, see note above)
yarn schema:fetch
- fetches OpenAPI schema from Discourseyarn schema:ts
- converts to TypeScript insrc/schema.d.ts
yarn generate
- generates method stubs insrc/generated.ts