Help Contents

 

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

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).

StatusDescription
200 - OKReturned if the request was completed successfully.
403 - ForbiddenReturned 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

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
tqlName ~ 'Report'The TQL query to execute.
$top5The maximum number of results to return (defaults to 25).
$skip0Number of results to skip before return the $top number of results matching the query.

Response Headers

KeyValueDescription
Content-Typeapplication/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

KeyValueDescription
Acceptapplication/json

Request Parameters

KeyValueDescription
$top5The maximum number of results to return (defaults to 25).
$skip0The Number of results to skip before return the $top number of results matching the query.

Response Headers

KeyValueDescription
Content-Typeapplication/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

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).

StatusDescription
200 - OKReturned if the request was completed successfully.

Example - Example

An example of creating a new requirement with only the minimum required information.

Request Headers

KeyValueDescription
Acceptapplication/json
Content-typeapplication/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

KeyValueDescription
Locationhttp://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/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

KeyValueDescription
Acceptapplication/json
Content-typeapplication/json

Request Parameters

KeyValueDescription
$expandFieldValuesExpand 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

KeyValueDescription
Locationhttp://localhost/api/requirement/4bb709c2-e0e7-4af3-9f60-a045016a9610
Content-Typeapplication/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