TypeScript client
Call the API with compile-time checked paths, parameters and bodies, using types generated from openapi.json and openapi-fetch.
The API is typed end to end by its OpenAPI document. In TypeScript, generate the types
once and call the API through openapi-fetch:
paths, parameters, bodies and responses are then checked at compile time.
Generate the types
npm install openapi-fetch
npx openapi-typescript https://www.ressource.social/api/v1/openapi.json -o ressource-api.d.tsRe-run the second command to pick up new routes.
Create a client
import createClient from "openapi-fetch";
import type { paths } from "./ressource-api";
export const api = createClient<paths>({
baseUrl: "https://www.ressource.social",
headers: { Authorization: `Bearer ${process.env.TOKEN}` },
});Paths in the document include the /api/v1 prefix, so the base URL is the www host
alone. Keep the www: the bare domain redirects, and the redirect drops the
Authorization header.
Call it
const { data, error } = await api.GET("/api/v1/sources", { params: { query: { limit: 20 } } });
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const source of data.items) console.log(source);
await api.POST("/api/v1/sources/quick", { body: { url: "https://example.com/" } });
await api.DELETE("/api/v1/sources/{id}", { params: { path: { id: "abc123XYZ" } } });error is the error envelope: branch on error.error.code,
never on the message. Lists come back as items, nextCursor and hasMore; see
Pagination.
ressource.social's own client
ressource.social's apps use @ressource/api-client/v1, a thin wrapper around exactly this:
createV1Client({ baseUrl, token }) sets the bearer header, or sends the session
cookie when no token is given. It lives in the ressource.social monorepo and is not
published to npm; the setup above is the equivalent for your own project.
Other languages
Generate a client from
openapi.json with the OpenAPI
generator of your choice. The document is OpenAPI 3.1.