Skip to main content

Valid Values (api/ValidValues)

Answers "what values may this relation take?" — the same question the application answers when it populates a dropdown, honoring the schema's valid-values filters (where the $ asset-identity variable does its work), the asking context, and Team Process. Both routes accept GET or POST and require authentication.

By Relation, with a Context​

GET ~/api/ValidValues/Story.Status/?context=Scope=Scope:1067

The path segment is the full attribute token. The trailing slash is required: the token contains a dot, and without a trailing slash the web server reads .Status as a file extension and answers 404 before the route is ever consulted. (The existing-asset form below has no dot in its last segment, so it needs no slash.)

ParameterMeaning
contextComma-separated Name=Oid pairs feeding the valid-values filter's variables. Omitted entirely, it defaults to Scope=Scope:0; an explicitly empty context= supplies no context at all, and typically returns nothing.
selAttributes to return per value; defaults to Name,ID.
sortAn attribute of the related type to sort by.

For an Existing Asset​

GET ~/api/ValidValues/Story/1207/Status

Evaluates the valid-values filter against the asset's actual state, so the answer reflects everything that narrows it — most usefully, a team's own workflow. On an instance whose shared StoryStatus list is Future / In Progress / Done / Accepted, a story on a team with its own process answers differently:

GET ~/api/ValidValues/Story/1207/Status
→ Ready, Dev, Dev Done, Test, Test Done, Accepted

This is the way to ask "which statuses may this workitem take?" before a write — the values a Team Process enforces on status changes. An optional teamoid parameter supplies the team explicitly. sel and sort work as above.

Response Shape​

The envelope looks like a rest-1.v1 list — _type: "Assets", total, Assets with id and Attributes — and each entry's href points at the asset's rest-1.v1 address:

{
  "_type": "Assets",
  "total": 4,
  "Assets": [
    {
      "_type": "Asset",
      "href": "~/rest-1.v1/Data/StoryStatus/133",
      "id": "StoryStatus:133",
      "Attributes": {
        "Name": { "_type": "Attribute", "name": "Name", "value": "Future" },
        "ID": { "_type": "Attribute", "name": "ID", "value": "StoryStatus:133" }
      }
    }
  ]
}

pageSize reports the no-limit sentinel; the endpoint does not page.

Quick Suggestions (api/QuickSuggestion)​

The same machinery has a lighter sibling, used for type-ahead:

GET ~/api/QuickSuggestion/Story:1207/Story.Status/

The first segment is the asset's OID, the second the full attribute token — and the trailing slash is required here for the same dot-in-the-last-segment reason. If the relation defines a quick-values filter (a schema-defined shortlist), the response has type: "Suggestions"; otherwise it falls back to the valid values, capped at 20, with type: "ValidValues":

{
  "data": {
    "type": "ValidValues",
    "data": [{ "_oid": "StoryStatus:133", "name": "Future" }]
  }
}

Use api/ValidValues when you need the complete, context-correct answer; api/QuickSuggestion when you want what the application would offer first in a type-ahead.