Public API: Inconsistent response format across list endpoints

[pneumatic-seidler]

Summary

This is an improvement proposal. If after review it is deemed unnecessary, this issue can be closed.

Problem

The Public API uses two different response formats for list/collection endpoints, breaking the principle of least surprise and forcing developers to handle responses differently depending on the endpoint.

Standard paginated wrapper (most endpoints):

{
  "count": N,
  "next": "url_or_null",
  "previous": "url_or_null",
  "results": [...]
}

Used by:

• GET /templates
• GET /accounts/users
• GET /workflows/fields

Flat array (no wrapper):

[ { ... }, { ... } ]

Used by:

• GET /v3/tasks

Impact

1. Generic API client code cannot assume a consistent response shape
2. Pagination metadata (count, next, previous) is unavailable for /v3/tasks
3. Developers must write endpoint-specific parsing logic
4. Any new list endpoint could follow either convention, creating uncertainty

This is especially confusing because GET /v2/tasks/<id> (single task) exists alongside GET /v3/tasks (list), and the list endpoint does not follow the standard DRF pagination pattern.

Proposed Solutions

Option A — New versioned endpoint (non-breaking):
Add GET /v4/tasks that returns the standard paginated wrapper { count, next, previous, results }. Deprecate /v3/tasks with a migration timeline.

Option B — Breaking change (major version):
Migrate /v3/tasks to return the standard paginated wrapper. Introduce as a breaking change in a new API version.

Option C — Documentation only (minimal):
Clearly document the inconsistency in the API docs and add a note explaining the flat array format for /v3/tasks.

Expected Outcome

All list endpoints return a consistent response format, allowing developers to write generic pagination and response-parsing code that works across all Pneumatic API resources.