Public API: Selection fields require opaque api_names instead of human-readable values

[pneumatic-seidler]

Summary

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

Problem

When setting values for radio, checkbox, and dropdown fields via the API (e.g., when launching a workflow via POST /templates/<ID>/run), developers must pass the selection api_name — an opaque, auto-generated identifier — rather than the human-readable display value.

Example

For a template with a "Service" field (type: radio), the selections are:

Display Value	Required api_name
frontend	selection-695823
backend	selection-50a890
storage	selection-1db8b1

To select "frontend", the API call must include "field-4b8af7": "selection-695823" instead of the intuitive "field-4b8af7": "frontend".

Issues this creates

1. Extra lookup step — developers must first call GET /templates/<ID> to retrieve the full selection list and build a mapping table before they can launch any workflow
2. Unreadable code — hardcoding values like "selection-695823" makes integration code difficult to understand and maintain
3. Simple integrations become complex — e.g., a Slack bot or webhook that launches a workflow with a human-readable parameter must maintain a translation layer
4. Brittle documentation — any documentation or examples must list the opaque api_names alongside display values

Root cause

In backend/src/processes/services/tasks/field.py, the _get_valid_radio_value method (lines 88–114) validates:

selection = selections.get(api_name=raw_value)

Only the api_name is matched. Passing the display value (e.g., "frontend") raises an ObjectDoesNotExist exception.

Proposed Solutions

Option A (Recommended) — Accept both api_name and display value:

try:
    selection = selections.get(api_name=raw_value)
except ObjectDoesNotExist:
    selection = selections.get(value__iexact=raw_value)

• Backward-compatible: existing api_name values still work
• Apply the same fallback to _get_valid_checkbox_value and _get_valid_dropdown_value

Option B — Better error messages:
Include valid options in the error message:

"Invalid selection for field 'Service'. Valid options: selection-695823 (frontend), selection-50a890 (backend), selection-1db8b1 (storage)"

Option C — Both:
Accept display values as a convenience layer, and improve error messages for invalid values.

Note on edge cases: If a selection display value happens to match another selection's api_name, Option A could produce ambiguous results. This is extremely unlikely but can be mitigated by always prioritizing api_name matches.

Expected Outcome

Developers can pass human-readable values like "frontend" or "Yes" to radio/checkbox/dropdown fields, making the API more intuitive and reducing the need to look up opaque identifiers.