Skip to content

API — Lookups & reference data

Purpose

The admin-CRUD surfaces for reference-data lookups, plus the read-only lookup catalog the UI uses to populate dropdowns. The eight CRUD groups all follow the lookup CRUD template; LookupsController is read-only.

Auth & roles

Each CRUD group gates reads on <entity>.view and writes on <entity>.config. Per the RBAC matrix, .config is typically SYS_ADMIN + HR_ADMIN (± PLANNER for some); .view extends to the operational roles.

Endpoints — admin CRUD (all under /api/admin/*)

Each group exposes the same five verbs: GET (list), POST (create), GET /{id}, PUT /{id}, DELETE /{id}.

Group Base route Gate (view / config)
Grades /api/admin/grades grade.view / grade.config
Skills (admin) /api/admin/skills skill.view / skill.config
Terminals /api/admin/terminals terminal.view / terminal.config
Node types /api/admin/node-types node_type.view / node_type.config
Holidays /api/admin/holidays holiday.view / holiday.config
Demand reasons /api/admin/demand-reasons demand_reason.view / demand_reason.config
Shift templates /api/admin/shift-templates shift_template.view / shift_template.config
Attendance statuses /api/admin/attendance-statuses attendance_status.view / attendance_status.config

Endpoints — read-only lookups

Lookups — base /api/lookups · [Authorize] (any authenticated user) · all GET

Path Returns
/api/lookups/departments · /nodes · /terminals Org structure options
/api/lookups/employee-statuses · /holiday-types Status / type options
/api/lookups/skill-categories · /skill-levels Skill taxonomy options
/api/lookups/demand-reasons Demand-reason options

Shapes & errors

CRUD bodies carry code + bilingual Name_1_English/Name_2_Arabic (+ optional D9 description — see Description fields). Delete is protected: 409 <ENTITY>_REFERENCED if FK-referenced, 409 <ENTITY>_PROTECTED if a system row (see Exceptions). code is immutable on update.

Gotchas

  • LookupsController is read-only — it serves dropdown data; it does not mutate. The writable surfaces are the /api/admin/* groups above.
  • Skills (admin) coexists with the production Skills group (/api/skills, on the employees/skills/certs page) — the coexistence pattern. Admin CRUD vs runtime read.
  • System rows can't be edited or deleted — only the non-system long tail is mutable.
  • Arabic-name requiredness is per entity (DemandReason leaves it optional; the rest require it).