Server Utilities & Remaining Endpoints

Overview

This document covers the system utility endpoints that don't fit into other categories: health checks, metrics, OpenAPI spec generation, and the broader set of system collection endpoints (notifications, comments, translations, shares, presets, settings).

Server Endpoints

GET /server/ping

Simple liveness check.

Auth required: No

Response:

pong

GET /server/health

Health check endpoint for load balancers and monitoring.

Auth required: No

Response:

json

{ "status": "ok" }

GET /server/info

Project information.

Auth required: No

Response:

json

{
  "data": {
    "project": {
      "name": "CMS",
      "url": "https://api.example.com",
      "node_env": "production"
    }
  }
}

GET /server/specs/oas

Auto-generated OpenAPI 3.0 specification based on the current database schema.

Auth required: Admin access

Response: Full OpenAPI 3.0 JSON document.

The spec is built dynamically from SchemaOverview:

System collections get dedicated paths (e.g., /users, /roles, /files)
User collections get paths under /items/{collection}
Singleton collections (e.g., /settings) only have GET and PATCH
Read-only collections (e.g., /activity) only have GET list and GET one
Hidden system tables (e.g., odp_sessions, odp_impersonation_sessions) are excluded

GET /server/metrics

Prometheus-compatible metrics output.

Auth required: Admin access

Response: Prometheus text format when METRICS_ENABLED = true.

# HELP odp_http_requests_total Total HTTP requests
# TYPE odp_http_requests_total counter
odp_http_requests_total{method="GET",route="/items/articles",status_code="200"} 42

Returns 404 if METRICS_ENABLED = false.

Configuration:

METRICS_ENABLED — Enable metrics collection (default: false)
METRICS_NAME_PREFIX — Prefix for metric names (default: odp_)

Import/Export

POST /utils/import/:collection

Import items into a collection from a file (CSV or JSON).

Auth required: Admin or collection write permission

GET /utils/export/:collection

Export collection items as CSV or JSON.

Auth required: Admin or collection read permission

System Collection Endpoints

All system collections follow the standard ODP CRUD pattern.

Notifications

Endpoints: GET/POST /notifications, GET/PATCH/DELETE /notifications/:id

Notifications are sent to specific users or roles and can be dismissed.

Key Fields:

recipient — UUID of the target user
collection, item — The content this notification is about
message — Notification message text
subject — Notification subject
status — inbox or archived

Comments

Endpoints: GET/POST /comments, GET/PATCH/DELETE /comments/:id

Comments are attached to specific items in any collection.

Key Fields:

collection — Collection name
item — Item primary key
comment — Comment text (supports Markdown)
user_created — Author
date_created, date_updated — Timestamps

Translations

Endpoints: GET/POST /translations, GET/PATCH/DELETE /translations/:id

User-defined string translations for internationalization.

Key Fields:

language — Language code (e.g., en-US, vi-VN)
key — Translation key
value — Translated string

Endpoints: GET/POST /shares, GET/PATCH/DELETE /shares/:id

Shares create public or password-protected access links to specific items.

Key Fields:

name — Share display name
collection — Shared collection
item — Shared item PK
role — Role applied to share access
password — Optional password (hashed)
date_start, date_end — Optional validity window
max_uses — Maximum number of uses
times_used — Usage counter

Presets

Endpoints: GET/POST /presets, GET/PATCH/DELETE /presets/:id

Presets store saved collection view configurations (filters, sort, fields) per user or globally.

Key Fields:

collection — Collection this preset applies to
user — UUID of the user (null = global default)
role — Role (null = specific user or global)
search — Saved search string
filters — JSON array of filter rules
layout — Layout type (e.g., tabular, cards)
layout_query — JSON layout query settings
layout_options — JSON layout display options
refresh_interval — Auto-refresh interval in seconds
icon — Preset icon
color — Preset color

Settings (Singleton)

Endpoints: GET /settings, PATCH /settings

Global project configuration. Only one record exists (id=1).

Key Fields:

Field	Description
`project_name`	Project display name
`project_url`	Public project URL
`project_color`	Brand color hex
`project_logo`	UUID → odp_files
`public_foreground`	Login page foreground image
`public_background`	Login page background image
`public_note`	Public login page note
`auth_login_attempts`	Max failed login attempts before lockout (default: 25)
`auth_password_policy`	Regex pattern or policy descriptor
`storage_asset_transform`	`all`, `none`, or `presets`
`storage_asset_presets`	JSON array of transform presets
`custom_css`	Custom CSS injected into admin app
`storage_default_folder`	Default upload folder UUID
`public_registration`	Allow public self-registration
`public_registration_verify_email`	Require email verification on registration
`public_registration_role`	Default role for self-registered users
`public_registration_email_filter`	JSON array of allowed email domains
`public_role`	UUID of the Public role (unauthenticated access)

Policies

Endpoints: GET/POST /policies, GET/PATCH/DELETE /policies/:id

Policies define access control rules. Roles and users are linked to policies via odp_access.

Key Fields:

name — Policy name
icon — Icon identifier
description — Description
ip_access — JSON array of CIDR ranges for IP restriction
enforce_tfa — Require TFA for users with this policy
admin_access — Grant admin dashboard access
app_access — Grant app (frontend) access

Permissions

Endpoints: GET/POST /permissions, GET/PATCH/DELETE /permissions/:id

Row-level RBAC permissions attached to policies.

Key Fields:

policy — UUID → odp_policies
collection — Collection name
action — create, read, update, delete, share
fields — JSON array of accessible fields (null = all)
permissions — JSON filter object (row-level conditions)
validation — JSON validation rules (for create/update)
presets — JSON default field values

Access

Endpoints: GET/POST /access, GET/PATCH/DELETE /access/:id

Junction table linking policies to roles or users.

Key Fields:

policy — UUID → odp_policies
role — UUID → odp_roles (optional)
user — UUID → odp_users (optional)
sort — Display order

Schema & Fields Endpoints

Collections

Endpoints: GET/POST /collections, GET/PATCH/DELETE /collections/:id

Metadata for database tables (both system and user-defined).

Fields

Endpoints: GET/POST /fields, GET/PATCH/DELETE /fields/:collection/:field

Field metadata, type information, display options, and validation rules.

Relations

Endpoints: GET/POST /relations, GET/PATCH/DELETE /relations/:id

Defines foreign key relationships between collections (M2O, O2M, M2M).

Configuration

Variable	Default	Description
`METRICS_ENABLED`	`false`	Enable Prometheus metrics
`METRICS_NAME_PREFIX`	`odp_`	Metric name prefix
`PRESSURE_ENABLED`	`true`	Enable event loop pressure detection
`MAX_PAYLOAD_SIZE`	`1mb`	Maximum request body size
`QUERYSTRING_MAX_PARSE_DEPTH`	`10`	Max nested depth for query string parsing

Server Utilities & Remaining Endpoints ​

Overview ​

Server Endpoints ​

GET /server/ping ​

GET /server/health ​

GET /server/info ​

GET /server/specs/oas ​

GET /server/metrics ​

Import/Export ​

POST /utils/import/:collection ​

GET /utils/export/:collection ​

System Collection Endpoints ​

Notifications ​

Comments ​

Translations ​

Shares ​

Presets ​

Settings (Singleton) ​

Policies ​

Permissions ​

Access ​

Schema & Fields Endpoints ​

Collections ​

Fields ​

Relations ​

Configuration ​

Server Utilities & Remaining Endpoints

Overview

Server Endpoints

GET /server/ping

GET /server/health

GET /server/info

GET /server/specs/oas

GET /server/metrics

Import/Export

POST /utils/import/:collection

GET /utils/export/:collection

System Collection Endpoints

Notifications

Comments

Translations

Shares

Presets

Settings (Singleton)

Policies

Permissions

Access

Schema & Fields Endpoints

Collections

Fields

Relations

Configuration