Use Cases

Get entity type by known entity ID

Make query:

GET /api/v1/Generals/12345

and check EntityType field in responce:

<EntityType ResourceType="EntityType" Id="17" Name="Request"/>

Get all Relations for entity

Make query:

GET /api/v1/features/132654?include=[Id,Name,MasterRelations[Master[Id,Name,EntityType],RelationType],SlaveRelations[Slave[Id,Name,EntityType],RelationType]]

Relations are shown in MasterRelations and SlaveRelations collections.

<Feature ResourceType="Feature" Id="132654" Name="v2 -> v3 full migration / public / phase 2">
    <Relation ResourceType="Relation" Id="16384">
      <Master ResourceType="Feature" Id="49122" Name="Batch Actions: Research">
        <EntityType ResourceType="EntityType" Id="9" Name="Feature"/>
      <RelationType ResourceType="RelationType" Id="1" Name="Dependency"/>

Get entities in selected states only

The following query helps to fetch projects that are in two states ("Planned" and "In Progress").

GET /api/v1/projects?include=[id,EntityState]&where=(EntityState.Name in ("Planned","In Progress"))

Filter entities by teams

Sometimes you may need to figure out a way to pull all of the user stories or features by a specific team. It is possible to use REST API for this purpose.


Team field is deprecated

With new Multiple Teams feature the "Team" field of Assignable API resource became deprecated. Please do not use "Team" field in API queries. Use "ResponsibleTeam" field and "AssignedTeams" collection both having "TeamAssignment" type instead.

Please use the following query to get the list of user stories assigned to a specific team (with ID #1234 in this case):

GET /api/v1/TeamAssignments?where=(Team.ID eq 1234) and (Assignable.EntityType.Name eq "UserStory")&include=[Assignable[ID,Name,AssignedTeams[Team]]]

Same works with other entity types. You can use known Name of the team. Say, get all features that are assigned to team "Alpha":

GET /api/v1/TeamAssignments?where=(Team.Name eq "Alpha") and (Assignable.EntityType.Name eq "Feature")&include=[Assignable[ID,Name,AssignedTeams[Team]]]

Add comment to user story

Make a call. In the request body you'll need to set Description field (that would be a text of the comment) and General field (that would refer to the numeric ID of the UserStory).

POST /api/v1/comments
Content-Type: application/json
  "Description":"test comment",