CRUD endpoints

The core of the product: every registered table, as a generic REST resource.

Table of contents

  1. Base address
  2. List rows — GET /crud/{table}
  3. Get one record — GET /crud/{table}/{column}/{value}
  4. Create a row — POST /crud/{table}
  5. Update a row — PUT /crud/{table}/{idColumn}/{idValue}
  6. Delete a row — DELETE /crud/{table}/{idColumn}/{idValue}
  7. Errors
  8. What permission a request actually needs

Base address

/api/v1/{tenant}/{database}/crud/{table}
  • {tenant} — the tenant’s slug.
  • {database} — the database’s own key (unique within that tenant; two different tenants may use the same database key, since the pair {tenant}/{database} together is what’s actually unique).
  • {table} — a real table name in that database. There is no separate step to “expose” a table — every table reachable by your credential’s role is already a live endpoint.

Every request needs a credential header — see Concepts → Authentication & credentials for which header to use for which credential type.

List rows — GET /crud/{table}

Returns every row the caller’s role and row policy allow, narrowed by whichever query parameters you send.

Parameter Example Does
filter ?filter=orders.status eq 'open' OData-style filter — see Filtering. Every column must be qualified as table.column (status alone is refused).
limit ?limit=50 Caps the number of rows returned.
orderBy ?orderBy=created_at:desc Sort order, as column:asc or column:desc; comma-separate for multiple columns (?orderBy=status:asc,created_at:desc).
groupBy ?groupBy=status Group rows by a column.
join ?join=customers Include related rows from a foreign-keyed table.
display ?display=name,email Return only the named columns.

An empty result set is a 404, the same as GET {table}/{column}/{value} below returning nothing — there’s no “200 with an empty array” case on either read path. If your integration treats “no rows matched” as a normal, expected outcome (e.g. a dashboard list that’s sometimes legitimately empty), handle a 404 from this endpoint as that case, not as an error to surface to a user.

Get one record — GET /crud/{table}/{column}/{value}

A convenience shortcut for “the row where {column} equals {value}” — equivalent to GET /crud/{table}?filter={table}.{column} eq '{value}'&limit=1, but returns the single object directly (or a 404) instead of an array.

curl -H "X-API-Key: drk_..." \
  "https://your-host/api/v1/acme/reports/crud/widgets/id/42"

Create a row — POST /crud/{table}

Body is a flat JSON object of column → value. If a row policy applies to the caller, its fixed columns (e.g. region = 'APAC') are automatically filled in on the created row — you don’t need to (and for a single-value policy column, can’t override it to something the policy forbids).

curl -X POST -H "X-API-Key: drk_..." -H "Content-Type: application/json" \
  -d '{"name":"New Widget","status":"active"}' \
  "https://your-host/api/v1/acme/reports/crud/widgets"

Returns the created row, including any server-assigned fields (auto-increment id, default timestamps).

Update a row — PUT /crud/{table}/{idColumn}/{idValue}

Body is the column(s) to change. Only the columns you send are touched. If a row policy applies, the target row must already match it — attempting to update a row outside your policy’s scope is refused, not silently redirected to a different row.

curl -X PUT -H "X-API-Key: drk_..." -H "Content-Type: application/json" \
  -d '{"status":"shipped"}' \
  "https://your-host/api/v1/acme/reports/crud/widgets/id/42"

Delete a row — DELETE /crud/{table}/{idColumn}/{idValue}

Same row-policy enforcement as update: a row outside your policy’s scope can’t be deleted, and the response for that case is a clear row_policy_forbidden, not a misleading 404 that implies the row never existed.

curl -X DELETE -H "X-API-Key: drk_..." \
  "https://your-host/api/v1/acme/reports/crud/widgets/id/42"

Errors

Every error response is JSON with at least error (a short machine-readable code) and errorDescription (a human-readable sentence). Common ones:

HTTP status error Meaning
401 unauthorized No credential, or it wasn’t recognized.
403 forbidden_action The credential’s role doesn’t hold the permission this action needs (e.g. widgets.delete).
403 row_policy_forbidden The target row exists, but is outside the caller’s row policy.
404 — No matching row(s) — from a list query that matched nothing, or a GET .../{column}/{value} whose value doesn’t exist.
400 server_error (with detail) Usually a filter whose column isn’t qualified as table.column — see Filtering.

What permission a request actually needs

Permissions are expressed as {table}.{action} — e.g. widgets.read, widgets.create, widgets.update, widgets.delete — and a role’s permissions use * as a wildcard for “every table” (*.read = read every table). There’s no separate “endpoint permission” concept distinct from the table name: if a role can {table}.read, the corresponding GET works; if it can’t, you get forbidden_action, not a 404 that hides whether the table even exists.


Copyright © CrudApi. Distributed under an open license.

This site uses Just the Docs, a documentation theme for Jekyll.