Expand
Overview
The Enterprise Tester REST API makes extensive use of a feature called Expand (also known as Expansions) - resources that support expanding will return the list of available expansions in a property of the representation, called "Expand" - here is an example of a "project" resource with a set of available expand values:
{
"Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
"Name": "Test Project",
"Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
"Expands": [
"Statuses",
"Priorities",
"RequirementTypes",
"RequirementStatuses",
"RequirementDifficulties",
"IncidentTypes",
"TestTypes",
"IncidentResolutions",
"IncidentStatuses",
"Versions",
"Components",
"ExecutionPackages",
"ScriptPackages",
"RequirementPackages"
]
}
When making a request, you can include a query parameter called $expand that provides a comma separated list of expands you wish to have expanded in the response - so for example, to get the priority and status picklists back with the project, you would use a request like this:
GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=Status,Priority
In the response those properties will be expanded, and will no longer be listed in the "Expands" property as available properties to expand.
{
"Id": "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
"Name": "Test Project",
"Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
"Expands": [
"RequirementTypes",
"RequirementStatuses",
"RequirementDifficulties",
"IncidentTypes",
"TestTypes",
"IncidentResolutions",
"IncidentStatuses",
"Versions",
"Components",
"ExecutionPackages",
"ScriptPackages",
"RequirementPackages"
],
"Priorities": [
{
"Id": "6b1e46f4-8b59-4dc3-8ed1-0b3b89612e34",
"Text": "Low",
"SortOrder": 1,
"Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/priority/6b1e46f4-8b59-4dc3-8ed1-0b3b89612e34"
},
{
"Id": "5d37d6a1-6b1d-4007-8fcf-2c5296af3740",
"Text": "High",
"SortOrder": 2,
"Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/priority/5d37d6a1-6b1d-4007-8fcf-2c5296af3740"
}
],
"Statuses": [
{
"Id": "753387d7-0a67-45bd-8b96-a58791c283bb",
"Text": "Draft",
"SortOrder": 1,
"Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/status/753387d7-0a67-45bd-8b96-a58791c283bb"
},
{
"Id": "023b39dc-31a3-4bb6-bf01-69da23de5d3f",
"Text": "Final",
"SortOrder": 2,
"Self": "http://localhost/api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9/status/023b39dc-31a3-4bb6-bf01-69da23de5d3f"
}
]
}
Expansions can be more than one level deep. Here is an example of getting a project, with its top level requirement package expanded, and each of those packages children collection expanded as well.
We do this by using a period (.) to navigate to the child expansion:
GET /api/project/593c2fb5-2300-4bce-ad50-9f07009b207c?$expand=RequirementPackages.Children
As you can see the child packages are then expanded as well:
{
"Expands" : [ "Components", ... ],
"Id" : "eb06e5d8-f774-4b0f-a95c-a911c13527a9",
"Name" : "Test Project",
"Self" : "/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9",
"RequirementPackages" : [{
"Id" : "d2353811-36f5-45cf-bb72-a0440092ab60",
"Name" : "Requirements",
"OrderNumber" : 0,
"Parent" : null,
"Self" : "http://localhost/api/requirementpackage/d2353811-36f5-45cf-bb72-a0440092ab60"
"Children" : [
{
"Expands" : [ "Children", "Parent" ],
"Id" : "87fcdd47-c8b5-4eb0-867b-a0440092ba61",
"Name" : "Traceability Matrix",
"OrderNumber" : 0,
"Self" : "http://localhost/api/requirementpackage/87fcdd47-c8b5-4eb0-867b-a0440092ba61"
},
{
"Expands" : [ "Children", "Parent" ],
"Id" : "ef3882a8-27b3-4a0c-9d54-a0440092bb81",
"Name" : "Business Requirements",
"OrderNumber" : 0,
"Self" : "http://localhost/api/requirementpackage/ef3882a8-27b3-4a0c-9d54-a0440092bb81"
},
{
"Expands" : [ "Children", "Parent" ],
"Id" : "7998df31-147d-4954-b6b6-a0440092bb8a",
"Name" : "Stakeholder Requirements",
"OrderNumber" : 0,
"Self" : "http://localhost/api/requirementpackage/7998df31-147d-4954-b6b6-a0440092bb8a"
},
{
"Expands" : [ "Children", "Parent" ],
"Id" : "f2a2c9ad-98c6-480c-b925-a0440092bbe9",
"Name" : "Non-Functional Requirements",
"OrderNumber" : 0,
"Self" : "http://localhost/api/requirementpackage/f2a2c9ad-98c6-480c-b925-a0440092bbe9"
}
],
"Expands" : [ "Parent" ],
}]
}
For each method supported by a resource (GET, POST, PUT) documented within the help system, we also include details of the available expansions.
Deep Expansion
You are not limited to expanding to one or two levels - to expand many levels of depth, you can continue to use a period character between each level i.e. RequirementPackages.Children. Children will return the requirement package, with its children and those children's children.
GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=RequirementPackages.Children.Children
As we can see the multiple levels are expanded as requested:
{
"Id": "c651ed19-5375-475a-a539-9f6401467130",
"Name": "Test Project",
"OrganisationId": "564a2bed-e152-4e58-a57d-9f4100888460",
"OrganisationName": "Acme Inc",
"Description": "Description of project",
"EstimatedEndDate": "2011-09-29T11:00:00Z",
"Slug": "test-project",
"AutoNumberRequirements": true,
"AutoNumberScripts": true,
"StartDate": "2011-08-14T12:00:00Z",
"Expands": [
"Components",
"ExecutionPackages",
"IncidentResolutions",
"IncidentStatuses",
"IncidentTypes",
"Priorities",
"RequirementDifficulties",
"RequirementStatuses",
"RequirementTypes",
"ScriptPackages",
"Statuses",
"TestTypes",
"TimeTrackingConfiguration",
"Versions"
],
"RequirementPackages": [
{
"Id": "53b483c7-e332-4d38-bf86-9fd700d552d2",
"ProjectId": "c651ed19-5375-475a-a539-9f6401467130",
"Name": "Requirements",
"OrderNumber": 0,
"Expands": [
"Parent",
"Project",
"Requirements"
],
"Children": [{
"Id": "f3b483c7-e332-4d38-bf86-9fd700d552d2",
"ProjectId": "c651ed19-5375-475a-a539-9f6401467130",
"ParentId": "53b483c7-e332-4d38-bf86-9fd700d552d2",
"Name": "Reports",
"OrderNumber": 0,
"Expands": [
"Parent",
"Project",
"Children": [...],
],
"Self": "http://localhost:29840/api/requirementpackage/f3b483c7-e332-4d38-bf86-9fd700d552d2"
}],
"Self": "http://localhost:29840/api/requirementpackage/53b483c7-e332-4d38-bf86-9fd700d552d2"
}
],
"Self": "http://localhost:29840/api/project/c651ed19-5375-475a-a539-9f6401467130"
}
'All' Expansion
When exploring the API it can be useful to expand everything, so you can see what information is available - this can be done through the pseudo-expansion "All" i.e.
GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=All
This will automatically be replaced with all available expands in the response:
{
"Id": "53b483c7-e332-4d38-bf86-9fd700d552d2",
"ProjectId": "c651ed19-5375-475a-a539-9f6401467130",
"Name": "Requirements",
"OrderNumber": 0,
"Children": [...],
"Parent": null,
"Project": {...},
"Requirements": [...],
"Self": "http://localhost:29840/api/requirementpackage/53b483c7-e332-4d38-bf86-9fd700d552d2"
}
You can use multiple levels of "All" as well - but we strongly advise against using "All" when writing code that interacts with the API as it will cause very large payloads to be returned and negatively impact on the performance of Enterprise Tester.