Date: Thu, 28 Mar 2024 21:28:19 +0000 (UTC) Message-ID: <582775921.9899.1711661299845@catch-kbase-p> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_9898_1896317797.1711661299844" ------=_Part_9898_1896317797.1711661299844 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
The Enterprise Tester REST API makes extensive use of a feature called <= strong>Expand (also known as Expansions) - resour= ces 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-a911c13527a= 9", "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 t= o have expanded in the response - so for example, to get the priority and s= tatus picklists back with the project, you would use a request like this:= p>
GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=3DStatus= ,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-a911c13527a= 9", "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-a911c13= 527a9/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-a911c13= 527a9/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-a911c13= 527a9/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-a911c13= 527a9/status/023b39dc-31a3-4bb6-bf01-69da23de5d3f" } ] }
Expansions can be more than one level deep. Here is an example of gettin= g a project, with its top level requirement package expanded, and each of t= hose 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=3DRequir= ementPackages.Children
As you can see the child packages are then expanded as well:
{=20 "Expands" : [ "Components", ... ], "Id" : "eb06e5d8-f774-4b0f-a95c-a911c13527a9", "Name" : "Test Project", "Self" : "/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9", "RequirementPackages" : [{ =20 "Id" : "d2353811-36f5-45cf-bb72-a0440092ab60", "Name" : "Requirements", "OrderNumber" : 0, "Parent" : null, "Self" : "http://localhost/api/requirementpackage/d2353811-36f5-45cf-= bb72-a0440092ab60" "Children" : [=20 { "Expands" : [ "Children", "Parent" ], "Id" : "87fcdd47-c8b5-4eb0-867b-a0440092ba61", "Name" : "Traceability Matrix", "OrderNumber" : 0, "Self" : "http://localhost/api/requirementpackage/87fcdd47-c8= b5-4eb0-867b-a0440092ba61" }, { "Expands" : [ "Children", "Parent" ], "Id" : "ef3882a8-27b3-4a0c-9d54-a0440092bb81", "Name" : "Business Requirements", "OrderNumber" : 0, "Self" : "http://localhost/api/requirementpackage/ef3882a8-27= b3-4a0c-9d54-a0440092bb81" }, { "Expands" : [ "Children", "Parent" ], "Id" : "7998df31-147d-4954-b6b6-a0440092bb8a", "Name" : "Stakeholder Requirements", "OrderNumber" : 0, "Self" : "http://localhost/api/requirementpackage/7998df31-14= 7d-4954-b6b6-a0440092bb8a" }, { "Expands" : [ "Children", "Parent" ], "Id" : "f2a2c9ad-98c6-480c-b925-a0440092bbe9", "Name" : "Non-Functional Requirements", "OrderNumber" : 0, "Self" : "http://localhost/api/requirementpackage/f2a2c9ad-98= c6-480c-b925-a0440092bbe9" } ], "Expands" : [ "Parent" ], }] =20 }
For each method supported by a resource (GET, POST, PUT) documented with= in the help system, we also include details of the available expansions.
You are not limited to expanding to one or two levels - to expand many l= evels of depth, you can continue to use a period character between each lev= el 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=3DRequir= ementPackages.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",=20 "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-e33= 2-4d38-bf86-9fd700d552d2" }], "Self": "http://localhost:29840/api/requirementpackage/53b483c7-e332-= 4d38-bf86-9fd700d552d2" } ], "Self": "http://localhost:29840/api/project/c651ed19-5375-475a-a539-9f640= 1467130" }
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-ex= pansion "All" i.e.
GET /api/project/eb06e5d8-f774-4b0f-a95c-a911c13527a9?$expand=3DAll
This will automatically be replaced with all available expands in the re= sponse:
{ "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 ag= ainst 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 perfo= rmance of Enterprise Tester.