Skip to content

ADR-006: Implement Task Sorting on the API Level

Field Value
Date 2026-03-22
Status Accepted
Deciders Project owner
Supersedes —
Superseded by —

Context and Problem Statement

UC006 requires the Task Manager to allow users to sort the task list by Status or Due Date. A decision must be made on where in the stack the sorting logic resides: in the backend (server-side, exposed as API query parameters) or in the React frontend (client-side, after loading all tasks).

Decision Drivers

  • Testability: the project's acceptance test strategy relies on Cucumber scenarios executed against the HTTP API via REST-Assured. Client-side behavior cannot be covered by this layer without introducing a separate browser E2E framework.
  • Forward compatibility: pagination is a foreseeable future requirement. Client-side sorting cannot produce a correctly sorted view when only one page of results is loaded.
  • API contract clarity: query parameters are the idiomatic REST mechanism for controlling the representation of a collection resource.

Considered Options

  1. Server-side sorting with named sort orders — a single optional sortBy query parameter on GET /api/tasks whose enum values (STATUS, ENDING_SOONEST, ENDING_LATEST) encode both the field and the direction; the backend returns an already-sorted list.
  2. Server-side sorting with separate field + direction parameters — sortBy and order query parameters; more flexible but exposes invalid combinations (e.g. STATUS DESC) and requires the client to construct the correct pair.
  3. Client-side sorting — the frontend receives an unsorted list and sorts it locally in the React component.

Decision Outcome

Chosen option: server-side sorting with named sort orders (option 1), because it keeps the behaviour testable with the existing Cucumber/REST-Assured acceptance test infrastructure, leaves the door open for pagination, and exposes only meaningful sort combinations through self-documenting enum values.

Positive Consequences

  • UC006 acceptance scenarios are expressed and verified at the HTTP level, consistent with UC001–UC005.
  • Adding pagination in the future does not require moving sorting logic.
  • The API contract makes the sort behaviour explicit and discoverable.

Negative Consequences / Risks

  • Requires a minor change to the API specification (additive, non-breaking).
  • Each sort-order change triggers a network request instead of an instant in-memory re-sort; acceptable at the expected data volume for this application.

Pros and Cons of the Options

Option 1 — Server-side sorting with named sort orders

  • Pro: Testable with Cucumber + REST-Assured; no additional test infrastructure needed.
  • Pro: Compatible with future pagination.
  • Pro: Each enum value is a complete, unambiguous sort specification — no invalid combinations possible (e.g. there is no STATUS DESC).
  • Pro: Sorting semantics (custom STATUS order, null handling for due dates) are centralised and consistent regardless of client.
  • Con: Additional network round-trip per sort interaction.

Option 2 — Server-side sorting with separate field + direction parameters

  • Pro: More flexible; a future PRIORITY field would not require new enum values.
  • Con: Exposes meaningless or contradictory combinations (e.g. STATUS DESC).
  • Con: Client must know which direction is valid for each field.

Option 3 — Client-side sorting

  • Pro: Instant UI response; no additional network requests.
  • Con: Cannot be covered by the existing acceptance test layer.
  • Con: Breaks silently when pagination is introduced (only the loaded page is sorted).