Resources / Requirements
Resource: Requirements ( /api/requirements )
Requirements collection resource
Root Relation: Requirements
This resource supports the following methods: GET, POST
Methods
GET
Retrieves all (or a subset) of requirements that are visible.
This method supports the TQL query parameters tql, $top, $take and $inlinecount. See TQL Topic for more details.
Required Permissions
TestManagement/ManageRequirements/View
Supported Expansions
Status
Priority
Type
DifficultyLevel
For more details on expansions, please see the Expand help topic.
Status Codes
These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
Status | Description |
|---|---|
200 - OK | Returned if the request was completed successfully. |
403 - Forbidden | Returned if ET could not complete the request (normally due to a validation failure or the necessary permissions to complete the request have not been met). |
Example - GET (filtered by TQL Query)
Retrieves requirements matching a TQL query
Request Headers
Key | Value | Description |
|---|---|---|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
tql | Name ~ 'Report' | The TQL query to execute. |
$top | 5 | The maximum number of results to return (defaults to 25). |
$skip | 0 | Number of results to skip before return the $top number of results matching the query. |
Response Headers
Key | Value | Description |
|---|---|---|
Content-Type | application/json; charset=utf-8 |
|
Response Body
{
"Skip": 0,
"Top": 5,
"Total": 1,
"Items": [
{
"Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Name": "Report pagination",
"AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"AssignedTo": "joeb",
"Description": "Check report pagination works correctly",
"PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
"StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
"TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
"DifficultyLevelId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
"CreatedAt": "2012-01-01T14:04:05Z",
"LastUpdatedAt": "2012-02-02T15:05:06Z",
"CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"CreatedBy": "joeb",
"LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"LastUpdatedBy": "joeb",
"Number": 1,
"EstimatedDuration": null,
"PackageId": "0f2c3a76-bbd1-4370-8faa-6aacb52f1a01",
"ParentId": null,
"OrderNumber": 0,
"ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
"ProjectName": "Test Project",
"ParentName": null,
"PackageName": "Cycle 1",
"ChangeComment": null,
"VersionNumber": 0,
"HasAttachments": false,
"Expands": [
"Widgets",
"FieldValues",
"Package",
"Assignments"
],
"Self": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Links": [
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
"Rel": "Relationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
"Rel": "AllRelationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
"Rel": "Comments"
}
]
}
],
"Self": "http://localhost/api/api/requirements?tql=Name~'Report'"
}
Status Code
200 - OK
Example - GET (no filter)
Retrieves all requirements.
Request Headers
Key | Value | Description |
|---|---|---|
Accept | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
$top | 5 | The maximum number of results to return (defaults to 25). |
$skip | 0 | The Number of results to skip before return the $top number of results matching the query. |
Response Headers
Key | Value | Description |
|---|---|---|
Content-Type | application/json; charset=utf-8 |
|
Response Body
{
"Skip": 0,
"Top": 5,
"Total": 2,
"Items": [
{
"Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Name": "Report pagination",
"AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"AssignedTo": "joeb",
"Description": "Check report pagination works correctly",
"PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
"StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
"TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
"DifficultyLevelId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
"CreatedAt": "2012-01-01T14:04:05Z",
"LastUpdatedAt": "2012-02-02T15:05:06Z",
"CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"CreatedBy": "joeb",
"LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"LastUpdatedBy": "joeb",
"Number": 1,
"EstimatedDuration": null,
"PackageId": "0f2c3a76-bbd1-4370-8faa-6aacb52f1a01",
"ParentId": null,
"OrderNumber": 0,
"ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
"ProjectName": "Test Project",
"ParentName": null,
"PackageName": "Cycle 1",
"ChangeComment": null,
"VersionNumber": 0,
"HasAttachments": false,
"Expands": [
"Widgets",
"FieldValues",
"Package",
"Assignments"
],
"Self": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Links": [
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
"Rel": "Relationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
"Rel": "AllRelationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
"Rel": "Comments"
}
]
},
{
"Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Name": "Login",
"AssignedToId": null,
"AssignedTo": null,
"Description": "Check report pagination works correctly",
"PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
"StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
"TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
"DifficultyLevelId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
"CreatedAt": "2012-03-01T14:04:05Z",
"LastUpdatedAt": "2012-03-02T15:05:06Z",
"CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"CreatedBy": "joeb",
"LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"LastUpdatedBy": "joeb",
"Number": 1,
"EstimatedDuration": null,
"PackageId": "0f2c3a76-bbd1-4370-8faa-6aacb52f1a01",
"ParentId": null,
"OrderNumber": 0,
"ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
"ProjectName": "Test Project",
"ParentName": null,
"PackageName": "Cycle 1",
"ChangeComment": null,
"VersionNumber": 0,
"HasAttachments": false,
"Expands": [
"Widgets",
"FieldValues",
"Package",
"Assignments"
],
"Self": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Links": [
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
"Rel": "Relationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
"Rel": "AllRelationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
"Rel": "Comments"
}
]
}
],
"Self": "http://localhost/api/api/requirements"
}
Status Code
200 - OK
POST
Creates a new requirement.
Required Permissions
TestManagement/ManageRequirements/Edit
Supported Expansions
Status
Priority
Type
DifficultyLevel
For more details on expansions, please see the Expand help topic.
Status Codes
These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
Status | Description |
|---|---|
200 - OK | Returned if the request was completed successfully. |
Example - Example
An example of creating a new requirement with only the minimum required information.
Request Headers
Key | Value | Description |
|---|---|---|
Accept | application/json |
|
Content-type | application/json |
|
Request Body
{
"PackageId": "0f2c3a76-bbd1-4370-8faa-6aacb52f1a01",
"Name": "My New Requirement",
"PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
"StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
"TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
"DifficultyLevelId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2"
}
Response Headers
Key | Value | Description |
|---|---|---|
Location | http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610 |
|
Content-Type | application/json; charset=utf-8 |
|
Response Body
{
"Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Name": "My New Requirement",
"AssignedToId": null,
"AssignedTo": null,
"Description": null,
"PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
"StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
"TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
"DifficultyLevelId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
"CreatedAt": "2012-01-01T14:04:05Z",
"LastUpdatedAt": "2012-02-02T15:05:06Z",
"CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"CreatedBy": "joeb",
"LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"LastUpdatedBy": "joeb",
"Number": 1,
"EstimatedDuration": null,
"PackageId": "0f2c3a76-bbd1-4370-8faa-6aacb52f1a01",
"ParentId": null,
"OrderNumber": 0,
"ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
"ProjectName": "Test Projec",
"ParentName": null,
"PackageName": "Cycle 1",
"ChangeComment": null,
"VersionNumber": 0,
"HasAttachments": false,
"Expands": [
"Widgets",
"FieldValues",
"Package",
"Assignments"
],
"Self": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Links": [
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
"Rel": "Relationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
"Rel": "AllRelationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
"Rel": "Comments"
}
]
}
Status Code
201 - Created
Example - Example
An example of creating a new requirement with majority of fields populated (including custom fields).
Request Headers
Key | Value | Description |
|---|---|---|
Accept | application/json |
|
Content-type | application/json |
|
Request Parameters
Key | Value | Description |
|---|---|---|
$expand | FieldValues | Expand field (FieldValues are expanded to ensure that they are returned in the response to creating a new requirement.) |
Request Body
{
"TemporaryId": "6cc26034-6514-44e0-907c-8f4f5eaa85b5",
"PackageId": "0f2c3a76-bbd1-4370-8faa-6aacb52f1a01",
"Number": 22,
"Name": "My New Requirement",
"AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"EstimatedDuration": "5m",
"PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
"StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
"TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
"DifficultyLevelId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
"Description": "derequiremention",
"ChangeComment": "Requirement created via my API",
"OrderNumber": 2,
"FieldValues": {
"Cycle": "V2.1 Cycle 1"
}
}
Response Headers
Key | Value | Description |
|---|---|---|
Location | http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610 |
|
Content-Type | application/json; charset=utf-8 |
|
Response Body
{
"Id": "4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Name": "My New Requirement",
"AssignedToId": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"AssignedTo": "joeb",
"Description": "derequiremention",
"PriorityId": "fe92720f-3fbd-4e49-a3b2-309f6a0a062a",
"StatusId": "62daf195-0a65-400f-af4b-7fda3d529acb",
"TypeId": "cfe51645-8179-4fe5-ada3-c145a64d0a05",
"DifficultyLevelId": "47b4b0cc-22ee-4993-8ed5-ef1dec40a0d2",
"CreatedAt": "2012-01-01T14:04:05Z",
"LastUpdatedAt": "2012-02-02T15:05:06Z",
"CreatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"CreatedBy": "joeb",
"LastUpdatedById": "191375f2-ae6e-4b52-8bed-4192e34b6486",
"LastUpdatedBy": "joeb",
"Number": 1,
"EstimatedDuration": "5 minutes",
"PackageId": "0f2c3a76-bbd1-4370-8faa-6aacb52f1a01",
"ParentId": null,
"OrderNumber": 22,
"ProjectId": "27dcaff0-1f8a-4dff-b49a-bb3d9f7153b3",
"ProjectName": "Test Projec",
"ParentName": null,
"PackageName": "Cycle 1",
"ChangeComment": "Requirement created via my API",
"VersionNumber": 1,
"HasAttachments": true,
"Expands": [
"Widgets",
"FieldValues",
"Package",
"Assignments"
],
"Self": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610",
"Links": [
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/relationships",
"Rel": "Relationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/allrelationships",
"Rel": "AllRelationships"
},
{
"Href": "http://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610/comments",
"Rel": "Comments"
}
]
}
Status Code
201 - Created