API design

Component-level vs Monolithic APIs

Component-Levels APIs were a natural fit for evalis, because they:

• provide granular control –> pre-empt accidental overwrites using a monolithic API
• simplify validation, and improve performance (flat structure update instead of deeply nested)
• align with progressive UX - lazy-load component when user navigates to it

  GET workflow: UI gets section IDs > then Section details API with id > … and so on.

• provide improved versioning without deep-copying (like git tracks only deltas)

Evalis API Hierarchy

Evaluation
   └── Evaluation Version
         └── Questionnaire
               └── Section
                     └── Question Group
                           └── Question

Endpoint patterns: Nested vs. Flat

• Nested style: when endpoints that list/create child resources, include the parent in the path.
  Example:
  • GET /evaluations/{evaluationId}/versions → list all versions of a specific evaluation
  • POST /evaluations/{evaluationId}/versions → create a new version under that evaluation
• Flat style: when endpoints operate on a single resource (get, update, delete), by directly using their ID:
• Example:
  • GET /versions/{versionId} → get details of one version
  • PUT /versions/{versionId}/status → update status of one version

Keeps list/create operations scoped to their parent,
while single-resource operations are simpler and shorter.