Requirements

This chapter focuses on services for the requirements.

Get all requirements

A GET to /requirements returns all the requirements that the user is allowed to read.

HTTP request

GET /api/rest/latest/requirements?page=2&size=1 HTTP/1.1
Accept: application/json
Host: localhost:8080

Request parameters

Parameter Description

page

number of the page to retrieve (optional)

size

size of the page to retrieve (optional)

sort

which attributes of the returned entities should be sorted on (optional)

fields

which fields of the elements should be returned (optional)

type

which type of the element should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1192

{
  "_embedded" : {
    "requirements" : [ {
      "_type" : "requirement",
      "id" : 60,
      "name" : "sample requirement",
      "current_version" : {
        "_type" : "requirement-version",
        "id" : 12,
        "reference" : "REQ_SAMP",
        "_links" : {
          "self" : {
            "href" : "http://localhost:8080/api/rest/latest/requirement-versions/12"
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/requirements/60"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements?page=0&size=1"
    },
    "prev" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements?page=1&size=1"
    },
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements?page=2&size=1"
    },
    "next" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements?page=3&size=1"
    },
    "last" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements?page=5&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 6,
    "totalPages" : 6,
    "number" : 2
  }
}

Response fields

Path Type Description

_embedded.requirements

Array

the list of elements for that page

page.size

Number

the page size for that query

page.totalElements

Number

total number of elements the user is allowed to read

page.totalPages

Number

how many pages can be browsed

page.number

Number

the page number

_links

Object

related links

Relation Description

first

link to the first page (optional)

prev

link to the previous page (optional)

self

link to this page

next

link to the next page (optional)

last

link to the last page (optional)

Create requirement

A POST to /requirements creates a new requirement.

HTTP request

POST /api/rest/latest/requirements HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 592
Host: localhost:8080

{
  "_type" : "requirement",
  "current_version" : {
    "_type" : "requirement-version",
    "name" : "new age",
    "criticality" : "MINOR",
    "category" : {
      "code" : "CAT_USER_STORY"
    },
    "status" : "UNDER_REVIEW",
    "description" : "<p>leave a comment please</p>",
    "custom_fields" : [ {
      "code" : "cuf_txt_note",
      "value" : "Star Trek style welcomed but not mandatory"
    }, {
      "code" : "cuf_tags_see_also",
      "value" : [ "smart home", "sensors", "hand gesture" ]
    } ]
  },
  "parent" : {
    "_type" : "requirement-folder",
    "id" : 300
  }
}

Request fields

Path Type Description

_type

String

the type of the entity (mandatory)

current_version

Object

the current requirement version of this requirement

parent

Object

the parent node of this requirement

Request parameters

Parameter Description

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 2094

{
  "_type" : "requirement",
  "id" : 456,
  "name" : "new age",
  "project" : {
    "_type" : "project",
    "id" : 15,
    "name" : "Winter will be gone",
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/projects/15"
      }
    }
  },
  "parent" : {
    "_type" : "requirement-folder",
    "id" : 300,
    "name" : "root-level folder",
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-folders/300"
      }
    }
  },
  "mode" : "NATIVE",
  "current_version" : {
    "_type" : "requirement-version",
    "id" : 333,
    "name" : "new age",
    "reference" : "SAMP_REQ_VER",
    "version_number" : 1,
    "created_by" : "admin",
    "created_on" : "2017-06-15T10:00:00.000+00:00",
    "last_modified_by" : "admin",
    "last_modified_on" : "2017-06-15T10:00:00.000+00:00",
    "criticality" : "MINOR",
    "category" : {
      "code" : "CAT_USER_STORY"
    },
    "status" : "UNDER_REVIEW",
    "description" : "<p>leave a comment please</p>",
    "custom_fields" : [ {
      "code" : "cuf_txt_note",
      "label" : "note",
      "value" : "Star Trek style welcomed but not mandatory"
    }, {
      "code" : "cuf_tags_see_also",
      "label" : "see also",
      "value" : [ "smart home", "sensors", "hand gesture" ]
    } ],
    "verifying_test_cases" : [ ],
    "attachments" : [ ],
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/333"
      }
    }
  },
  "versions" : [ {
    "_type" : "requirement-version",
    "id" : 333,
    "name" : "new age",
    "version_number" : 1,
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/333"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements/456"
    },
    "project" : {
      "href" : "http://localhost:8080/api/rest/latest/projects/15"
    },
    "current_version" : {
      "href" : "http://localhost:8080/api/rest/latest/requirement-versions/333"
    }
  }
}

Response fields

Path Type Description

id

Number

the id of the requirement

name

String

the name of the current (latest) requirement version of this requirement

project

Object

the project which this requirement belongs to

mode

String

the management mode of the requirement

versions

Array

the requirement versions of this requirement

_links

Object

related links

Relation Description

self

link to this requirement

project

link to the project this requirement belongs to

current_version

link to the current version of this requirement

Modify requirement

A PATCH to /requirements/{id} modifies the requirement with the given id. The properties that you can modify are the name, reference, description, category, criticality and status.

Note that modifying a requirement means modifying its current version : this is why those attributes must be enclosed in a section "current_version" (see the example).

Path parameters

Table 1. /api/rest/latest/requirements/{id}
Parameter Description

id

the id of the requirement.

HTTP request

PATCH /api/rest/latest/requirements/60 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 562
Host: localhost:8080

{
  "_type" : "requirement",
  "current_version" : {
    "_type" : "requirement-version",
    "name" : "new age after modify",
    "reference" : "SAMP_REQ_VER",
    "criticality" : "MAJOR",
    "category" : {
      "code" : "CAT_USER_STORY"
    },
    "status" : "APPROVED",
    "description" : "<p>Comment after modify</p>",
    "custom_fields" : [ {
      "code" : "cuf_txt_note",
      "value" : "Star Trek style welcomed but not mandatory"
    }, {
      "code" : "cuf_tags_see_also",
      "value" : [ "smart home", "sensors", "hand gesture" ]
    } ]
  }
}

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2127

{
  "_type" : "requirement",
  "id" : 60,
  "name" : "new age after modify",
  "project" : {
    "_type" : "project",
    "id" : 14,
    "name" : "sample project",
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/projects/14"
      }
    }
  },
  "parent" : {
    "_type" : "requirement-folder",
    "id" : 300,
    "name" : "sample folder",
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-folders/300"
      }
    }
  },
  "mode" : "NATIVE",
  "current_version" : {
    "_type" : "requirement-version",
    "id" : 36,
    "name" : "new age after modify",
    "reference" : "SAMP_REQ_VER",
    "version_number" : 1,
    "created_by" : "admin",
    "created_on" : "2017-06-15T10:00:00.000+00:00",
    "last_modified_by" : "admin",
    "last_modified_on" : "2017-06-15T10:00:00.000+00:00",
    "criticality" : "MAJOR",
    "category" : {
      "code" : "CAT_USER_STORY"
    },
    "status" : "APPROVED",
    "description" : "<p>Comment after modify</p>",
    "custom_fields" : [ {
      "code" : "cuf_txt_note",
      "label" : "note",
      "value" : "Star Trek style welcomed but not mandatory"
    }, {
      "code" : "cuf_tags_see_also",
      "label" : "see also",
      "value" : [ "smart home", "sensors", "hand gesture" ]
    } ],
    "verifying_test_cases" : [ ],
    "attachments" : [ ],
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/36"
      }
    }
  },
  "versions" : [ {
    "_type" : "requirement-version",
    "id" : 36,
    "name" : "new age after modify",
    "version_number" : 1,
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/36"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements/60"
    },
    "project" : {
      "href" : "http://localhost:8080/api/rest/latest/projects/14"
    },
    "current_version" : {
      "href" : "http://localhost:8080/api/rest/latest/requirement-versions/36/current_version"
    }
  }
}

Get requirement

A GET to /requirements/{id} returns the requirement with the given id.

Path parameters

Table 1. /api/rest/latest/requirements/{id}
Parameter Description

id

the id of the requirement

HTTP request

GET /api/rest/latest/requirements/624 HTTP/1.1
Accept: application/json
Host: localhost:8080

Request parameters

Parameter Description

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3338

{
  "_type" : "requirement",
  "id" : 624,
  "name" : "sample requirement 98-3",
  "project" : {
    "_type" : "project",
    "id" : 44,
    "name" : "sample project",
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/projects/44"
      }
    }
  },
  "path" : "/sample project/domain 1/sample requirement 98-3",
  "parent" : {
    "_type" : "requirement-folder",
    "id" : 6,
    "name" : "domain 1",
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-folders/6"
      }
    }
  },
  "mode" : "NATIVE",
  "current_version" : {
    "_type" : "requirement-version",
    "id" : 98,
    "name" : "sample requirement 98-3",
    "reference" : "REQ01",
    "version_number" : 3,
    "created_by" : "User-1",
    "created_on" : "2017-07-17T10:00:00.000+00:00",
    "last_modified_by" : "User-1",
    "last_modified_on" : "2017-07-17T10:00:00.000+00:00",
    "criticality" : "MAJOR",
    "category" : {
      "code" : "CAT_FUNCTIONAL"
    },
    "status" : "WORK_IN_PROGRESS",
    "description" : "<p>Description of the sample requirement.</p>",
    "custom_fields" : [ {
      "code" : "CF_TXT",
      "label" : "cuf text",
      "value" : "text value"
    }, {
      "code" : "CF_TAG",
      "label" : "cuf tag",
      "value" : [ "tag_1", "tag_2" ]
    } ],
    "verifying_test_cases" : [ {
      "_type" : "test-case",
      "id" : 100,
      "name" : "sample test case 1",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/test-cases/100"
        }
      }
    }, {
      "_type" : "scripted-test-case",
      "id" : 102,
      "name" : "sample scripted test case 2",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/test-cases/102"
        }
      }
    }, {
      "_type" : "keyword-test-case",
      "id" : 103,
      "name" : "sample keyword test case 3",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/test-cases/103"
        }
      }
    } ],
    "attachments" : [ ],
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/98"
      }
    }
  },
  "versions" : [ {
    "_type" : "requirement-version",
    "id" : 78,
    "name" : "sample requirement 98-1",
    "version_number" : 1,
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/78"
      }
    }
  }, {
    "_type" : "requirement-version",
    "id" : 88,
    "name" : "sample requirement 98-2",
    "version_number" : 2,
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/88"
      }
    }
  }, {
    "_type" : "requirement-version",
    "id" : 98,
    "name" : "sample requirement 98-3",
    "version_number" : 3,
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/98"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements/624"
    },
    "project" : {
      "href" : "http://localhost:8080/api/rest/latest/projects/44"
    },
    "current_version" : {
      "href" : "http://localhost:8080/api/rest/latest/requirement-versions/98"
    }
  }
}

Response fields

Path Type Description

id

Number

the id of the requirement

_type

String

the type of the entity

name

String

the name of the current (latest) requirement version of this requirement

project

Object

the project which this requirement belongs to

path

String

the path of this requirement

parent

Object

the parent node of this requirement

mode

String

the management mode of the requirement

current_version

Object

the current requirement version of this requirement

versions

Array

the requirement versions of this requirement

_links

Object

related links

Relation Description

self

link to this requirement

project

link to the project this requirement belongs to

current_version

link to the current version of this requirement

Delete requirement

A DELETE to /requirements/{ids} deletes one or several requirement(s) with the given id(s).

Path parameters

Table 1. /api/rest/latest/requirements/{ids}
Parameter Description

ids

the list of ids of the requirements

HTTP request

DELETE /api/rest/latest/requirements/169,189 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Get requirement children

A GET to /requirements/{id}/children returns the children of the requirement with the given id.

Path parameters

Table 1. /api/rest/latest/requirements/{id}/children
Parameter Description

id

the id of the requirement

HTTP request

GET /api/rest/latest/requirements/99/children?page=2&size=2 HTTP/1.1
Accept: application/json
Host: localhost:8080

Request parameters

Parameter Description

page

number of the page to retrieve (optional)

size

size of the page to retrieve (optional)

sort

which attributes of the returned entities should be sorted on (optional)

fields

which fields of the elements should be returned (optional)

include

level of depth of the content that should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1645

{
  "_embedded" : {
    "children" : [ {
      "_type" : "requirement",
      "id" : 47,
      "name" : "sample requirement 1",
      "current_version" : {
        "_type" : "requirement-version",
        "id" : 33,
        "reference" : "REQ_SAMP_1",
        "_links" : {
          "self" : {
            "href" : "http://localhost:8080/api/rest/latest/requirement-versions/33"
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/requirements/47"
        }
      }
    }, {
      "_type" : "requirement",
      "id" : 88,
      "name" : "sample requirement 2",
      "current_version" : {
        "_type" : "requirement-version",
        "id" : 11,
        "reference" : "REQ_SAMP_2",
        "_links" : {
          "self" : {
            "href" : "http://localhost:8080/api/rest/latest/requirement-versions/11"
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/requirements/88"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements/99/children?page=0&size=2"
    },
    "prev" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements/99/children?page=1&size=2"
    },
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements/99/children?page=2&size=2"
    },
    "last" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements/99/children?page=2&size=2"
    }
  },
  "page" : {
    "size" : 2,
    "totalElements" : 6,
    "totalPages" : 3,
    "number" : 2
  }
}

Response fields

Path Type Description

_embedded.children

Array

the list of elements for that page

page.size

Number

the page size for that query

page.totalElements

Number

total number of elements the user is allowed to read

page.totalPages

Number

how many pages can be browsed

page.number

Number

the page number

_links

Object

related links

Relation Description

first

link to the first page (optional)

prev

link to the previous page (optional)

self

link to this page

next

link to the next page (optional)

last

link to the last page (optional)

A POST to /requirements/{id}/coverages/{testCaseIds} link the test cases to the requirement.

Table 1. /api/rest/latest/requirements/{id}/coverages/{testCaseIds}
Parameter Description

id

the id of the requirement

testCaseIds

the ids of the test cases to associate

POST /api/rest/latest/requirements/543/coverages/350,351,352 HTTP/1.1
Accept: application/json
Host: localhost:8080
Parameter Description

fields

which fields of the elements should be returned (optional)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2640

{
  "_type" : "requirement",
  "id" : 543,
  "name" : "User friendly interface",
  "project" : {
    "_type" : "project",
    "id" : 5,
    "name" : "Application-5",
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/projects/5"
      }
    }
  },
  "parent" : {
    "_type" : "requirement-folder",
    "id" : 305,
    "name" : "User Interface Folder",
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-folders/305"
      }
    }
  },
  "mode" : "NATIVE",
  "current_version" : {
    "_type" : "requirement-version",
    "id" : 658,
    "name" : "User friendly interface",
    "reference" : "UX-5",
    "version_number" : 1,
    "created_by" : "admin",
    "created_on" : "2017-06-15T10:00:00.000+00:00",
    "last_modified_by" : "admin",
    "last_modified_on" : "2017-06-15T10:00:00.000+00:00",
    "criticality" : "MAJOR",
    "category" : {
      "code" : "CAT_ERGONOMIC"
    },
    "status" : "WORK_IN_PROGRESS",
    "description" : "<p>User interface is minimalist and easy to use.</p>",
    "custom_fields" : [ {
      "code" : "AUTOMATED",
      "label" : "test_is_automated",
      "value" : "false"
    } ],
    "verifying_test_cases" : [ {
      "_type" : "test-case",
      "id" : 350,
      "name" : "Verify click number",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/test-cases/350"
        }
      }
    }, {
      "_type" : "test-case",
      "id" : 351,
      "name" : "Verify element number",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/test-cases/351"
        }
      }
    }, {
      "_type" : "test-case",
      "id" : 352,
      "name" : "Verify page space",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/test-cases/352"
        }
      }
    } ],
    "attachments" : [ ],
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/658"
      }
    }
  },
  "versions" : [ {
    "_type" : "requirement-version",
    "id" : 658,
    "name" : "User friendly interface",
    "_links" : {
      "self" : {
        "href" : "http://localhost:8080/api/rest/latest/requirement-versions/658"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/requirements/543"
    },
    "project" : {
      "href" : "http://localhost:8080/api/rest/latest/projects/5"
    },
    "current_version" : {
      "href" : "http://localhost:8080/api/rest/latest/requirement-versions/658"
    }
  }
}
Path Type Description

_type

String

type of the entity

id

Number

the id of the requirement

name

String

the name of the current (latest) requirement version of this requirement

mode

String

the management mode of the requirement

project

Object

the project the requirement belongs to

parent

Object

the parent of this requirement

current_version

Object

the current requirement version of this requirement

versions

Array

the requirement versions of this requirement

_links

Object

related links

Relation Description

self

link to this requirement

project

link to the project this requirement belongs to

current_version

link to the current version of this requirement

A DELETE to /requirements/{id}/coverages/{testCaseIds} unlink the test cases from the requirement.

Table 1. /api/rest/latest/requirements/{id}/coverages/{testCaseIds}
Parameter Description

id

the id of the requirement

testCaseIds

the ids of the test cases to disassociate

DELETE /api/rest/latest/requirements/543/coverages/350,351 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080