Public API documentation

Write for a developer choosing an endpoint and making a request. Verify each claim against its schema, handler, and available response fixtures. API source owns the contract; regenerate OpenAPI and the reference after editing it.

Wording

Use present tense, concrete nouns, and direct verbs. Begin with the useful fact. Remove openings such as “This endpoint allows you to” and unnecessary contrasts such as “enrichment, not discovery”. Avoid vague claims about rich insights, complete coverage, or real-time data. Use consistent terms within a platform.

Keep conditions that affect a request or response. Do not remove a required matching token, date dependency, cursor, approximate-count meaning, or empty result just to shorten a sentence. Schema tables already show types, required flags, defaults, and bounds; prose should explain what those declarations cannot. Implementation history, parsing decisions, suppliers, and retry mechanics belong in internal documentation. Public fields that expose controls still need an accurate explanation of their behavior.

Examples:

• Description: “Get a RedNote product's name, displayed price, and seller details.”
• Input: “Listing ID from the id field in a stay search result.”
• Response: “An unknown stay_id returns data: null.”
• Dependency: “Token from the same card as user_id.”

Overview pages and search

Use the shared platform overview layout: platform name and capability paragraph, endpoint catalog grouped by task, practical applications, a starting request, relevant coverage details, and a signup action. Populate paths, methods, prices, and operation flags from OpenAPI. Write distinct introductions grounded in each platform's actual capabilities. Do not pad pages to a word count.

Use “Get an API key” for signup and link to the existing signup flow. Describe only supported actions: Airbnb reads listings and calendars; it does not create reservations. Publish request and response examples only after verifying them; label response excerpts and never invent successful payloads.

Give each platform and operation a descriptive title and useful description. Example: “Airbnb API: Listings, Reviews and Availability”. Render readable content and endpoint links on the server. Keep stable URLs, redirects, canonicals, and sitemaps consistent. Wording edits must not break previously published links. See search visibility for indexing verification.

Owner check mark

Worker-backed groups carry workerBacked: true in route-catalog.json. Mixed groups list exact method/path exceptions in workerBackedExceptions. Record this from the service implementation, never infer it from a version or platform name.

Set an operation's exact operationId to true or false in route-verification.json to override the default. This works for any route, including external-backed routes. Canonical and legacy aliases share their operation identity. Remove an override to restore the worker default. The emitter rejects unknown IDs and invalid values.

Only the resulting x-toolzer-verified boolean enters public OpenAPI. The docs show a small green check with a short screen-reader name. There is no visible label, tooltip, legend, supplier label, or reliability explanation.

Review and validation

Read schemas, handlers, and fixtures before rewriting. Preserve paths, IDs, request rules, response shapes, credit prices, and accurate behavior. Check identifier compatibility before linking related operations. Compare generated contracts after a copy pass; do not change handlers to fit a nicer sentence.

The existing emitter/importer enforces required operation text and length limits. Reference integrity is checked by the API publication builder. Human review must still establish accuracy and usefulness. Avoid exact-copy snapshots, arbitrary word blacklists, or one test file per description.

Sources: Google API writing guidance, Microsoft sentence guidance, Google helpful content, Google title guidance.