Typed clients and the reference

The reference

The full reference, with every operation, field, example and error response, is the API documentation page in the company’s admin, under Developers. It is not public: it opens for a staff member whose role includes reading the API documentation, behind the company’s two-step sign-in and its network access list. It contains no company data.

If you build for a company, ask for a role that opens it, or ask a staff member to save the schema for you from the link under the page’s title.

The schema

The schema is OpenAPI 3, generated from the product itself, so it never drifts from what the API does. Version 1 only gains fields and operations, and a released schema is never changed in a breaking way (see Conventions).

Generating types

Generate types from the schema instead of writing them by hand. For TypeScript:

npx openapi-typescript ./openapi.json -o src/api-types.d.ts

Then a read is typed end to end:

import type { paths } from "./api-types";
 
type ListingPage = paths["/api/v1/listings"]["get"]["responses"]["200"]["content"]["application/json"];
 
const page: ListingPage = await (await fetch(`https://${host}/api/v1/listings?type=sale`)).json();

Other languages have equivalent generators for OpenAPI 3. Majali does not ship a client library; the schema is the contract.

Keeping up

• Watch the product changelog for new fields and operations; nothing you rely on will disappear from v1.
• Regenerate types when you fetch a new schema; your build then tells you what is new.