Insert

An insert endpoint is a write that adds a record to one collection. It names which columns the caller may supply, which are required, and any public names they carry; it can also set fixed values for columns the caller never sees. It is the datahoster-endpoint-insert.json file in an endpoint folder; its presence makes that endpoint accept a POST that adds a record.

{
  "datahoster-endpoint-insert-collection": "messages",
  "datahoster-endpoint-insert-fields": [
    {
      "datahoster-endpoint-insert-field-of": "name",
      "datahoster-endpoint-insert-field-as": "yourName",
      "datahoster-endpoint-insert-field-required": true
    },
    {
      "datahoster-endpoint-insert-field-of": "email",
      "datahoster-endpoint-insert-field-required": true
    },
    {
      "datahoster-endpoint-insert-field-of": "message",
      "datahoster-endpoint-insert-field-required": true
    }
  ],
  "datahoster-endpoint-insert-values": [
    {
      "datahoster-endpoint-insert-value-of": "handled",
      "datahoster-endpoint-insert-value": false
    }
  ],
  "datahoster-endpoint-insert-redirect": "https://example.com/contact/thanks/",
  "datahoster-endpoint-insert-public": true,
  "datahoster-endpoint-insert-users": []
}

A public submit: anyone may add a message; handled is forced to false.

The file is one JSON object; its keys are fixed names starting with datahoster-endpoint-insert-. The example above, in a submit/ endpoint, lets anyone add a messages record, taking a name, email and message, and marking it unhandled.

Name	Type	Description
`datahoster-endpoint-insert-collection`	text	The collection a record is added to. Required.
`datahoster-endpoint-insert-fields`	array	The columns the caller may supply, each optionally renamed or required.
`datahoster-endpoint-insert-values`	array	Fixed values the endpoint sets itself, for columns the caller never provides. Optional.
`datahoster-endpoint-insert-redirect`	text	Where a browser form POST lands on success, as a `303` redirect (typically a thank-you page). A JSON request ignores it and gets the new record. Optional; without it a form POST gets a plain thank-you page (a `200`).
`datahoster-endpoint-insert-public`	boolean	Whether anyone may call it, with no token. Defaults to `false`.
`datahoster-endpoint-insert-users`	array	The users who may call it, each proving a token. Defaults to `[]`.

datahoster-endpoint-insert-fields

The columns the caller may supply. Each element names a collection column with -field-of, may expose it under a public name with -field-as, and may mark it -field-required. A column the caller omits takes its column default; a required field the caller omits is a 400. A column that is neither a field nor a value keeps its default.

Name	Type	Description
`datahoster-endpoint-insert-field-of`	text	The column the caller may set. Required.
`datahoster-endpoint-insert-field-as`	text	The name the caller supplies it under. Defaults to the column's own name.
`datahoster-endpoint-insert-field-required`	boolean	`true` to reject a POST that omits it. Defaults to `false`.

datahoster-endpoint-insert-values

Fixed values the endpoint writes itself, for columns the caller cannot set. Each element names a column with -value-of and the value to store with -value. This is how an endpoint stamps a record: a status, a source tag, a flag.

Name	Type	Description
`datahoster-endpoint-insert-value-of`	text	The column to set. Required.
`datahoster-endpoint-insert-value`	the column's type	The value stored in every record this endpoint inserts. Required.

HTTP request

POST the endpoint's path, at <domain>/<endpoint>, with the fields as a form or a JSON body, under their public names. If the endpoint is not public, send the user's token as a bearer token. The response carries the new record's id. A request that is not allowed — no token where one is needed, a wrong token, or a user this endpoint does not list — gets the same 404 as a path with no endpoint.

POST https://api.example.com/submit
Content-Type: application/x-www-form-urlencoded

yourName=Ada&email=ada@example.com&message=Hello

An HTML form pointed at the submit endpoint.

Status	Meaning
`201`	The record was added (a JSON request); the response holds its `id`.
`200`	A browser form POST succeeded and no redirect is set: a plain thank-you page is shown.
`303`	A browser form POST succeeded and a redirect is set: the browser is sent to `datahoster-endpoint-insert-redirect`, or to the form's own `_redirect` field if it carries one.
`400`	A required field is missing, or a value fails its column's type or is too large for it.
`413`	The request body is larger than the server accepts.
`404`	No insert endpoint answers on this path, or the caller is not allowed it — a missing token, an invalid one, or a user the endpoint does not list. The two are indistinguishable, so a probe cannot tell the endpoint is there.

Insert

Contents

datahoster-endpoint-insert-fields

datahoster-endpoint-insert-values

HTTP request