API Design

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.