dimah-formv0.6.1
Reference

Protocol

HTTP routes, client methods, and form.api calls.

Paths and payloads live in @dimah-form/core. Default prefix: /api/form.

Client methods are on createFormClient(). Server methods are form.api.* and take { query } or { body }, plus optional headers for guard.

List endpoints default to 50 rows and cap at 100.

Forms

MethodPathClientform.api
GET/formgetForm({ formId })getForm({ query })
POST/formsaveForm(form)saveForm({ body })
POST/form/deletedeleteForm({ formId })deleteForm({ body })
GET/formslistForms({ status?, limit?, offset? })listForms({ query })

formId is an id or a slug. saveForm and deleteForm reject code-authored forms (CODE_AUTHORED_FORM). deleteForm also rejects a form that still has responses (FORM_HAS_RESPONSES). listForms returns { forms, limit, offset, nextOffset }. When updating a database-authored form, include its last updatedAt; a concurrent write fails with STALE_UPDATE.

Responses

MethodPathClientform.api
POST/response/startstartResponse({ formId, respondentId?, resume? })startResponse({ body })
GET/responsegetResponse({ responseId })getResponse({ query })
GET/responseslistResponses({ formId?, respondentId?, status?, submittedFrom?, submittedTo?, updatedAfter?, include?, limit?, offset? })listResponses({ query })
POST/response/draftsaveDraft({ responseId, answers, updatedAt? })saveDraft({ body })
POST/response/submitsubmitResponse({ responseId, answers?, updatedAt? })submitResponse({ body })
POST/response/abandonabandonResponse({ responseId, updatedAt? })abandonResponse({ body })
POST/response/reopenreopenResponse({ responseId, updatedAt? })reopenResponse({ body })
POST/response/deletedeleteResponse({ responseId })deleteResponse({ body })

listResponses returns summaries unless include is "full". total is the matching count, not the page size. submittedFrom / submittedTo are inclusive and skip rows with no submittedAt. updatedAfter is an exclusive lower bound on updatedAt.

import type { ResponseListFilter } from "@dimah-form/server";

Prop

Type

Payloads

startResponse freezes the definition and seeds defaultValue. resume: true needs respondentId and returns the latest draft when one exists.

saveDraft.answers is a patch; null deletes that key. submitResponse.answers, when present, replaces the complete answer map. Omit it to submit the stored draft. Send updatedAt from the last read — a mismatch is 409 STALE_UPDATE.

submitResponse evaluates showWhen, drops hidden answers, then checks every visible field. Success sets status: "submitted" and submittedAt.

The success body is a ResponseRecord, except list routes, which return a page.

Plugin routes

Plugin routes use the same basePath. Their method name is also the default guard.operation.

PackageMethod and pathClient and form.api method
ScoringGET /scoring/responsegetResponseScores
DatasetGET /dataset/responsesgetDatasetPage
DatasetGET /dataset/codebook/historygetDatasetCodebook
DatasetGET /dataset/codebookgetLiveCodebook
InsightsGET /insights/summarygetFormInsights
InsightsGET /insights/crosstabgetFormCrosstab

Install the matching *ClientPlugin() to expose these methods in the browser. Authorize Dataset and Insights as administrative reads; Scoring reads a stored response and should follow the same ownership policy as getResponse.

Next steps

On this page