API - Requirements

Additional information

Custom fields

If you have custom fields setup for requirements within the given project, the custom field data is exposed here. It is recommend that you take a look at the custom field resource documentation which will explain the format and how to match the values to the field names / ID's.

List

Description: Provides a paginated list of all requirements within a given requirement document.

Endpoint: <base_url>/v1/projects/{project_id}/requirement_documents/{requirement_document_id}/requirements.json

Request: GET

Formats supported: JSON

Params:

  • project_id - {Integer} The associated project ID (Required)
  • requirement_document_id - {Integer} The associated requirement document ID (Required)
  • page - {Integer} of the page (Default: 1)

Response

{
  "pagination": { .... },
  "requirements": [
    {
....,
"custom_fields": [
{ .... },
{ .... }
]
},
    {
....,
"custom_fields": [
{ .... },
{ .... }
]
}
  ]
}

Example ruby request

HTTParty.get('https://example.api.testlodge.com/v1/projects/1/requirement_documents/1/requirements.json')

Example Response

Response code: 200

{
  "pagination": {
    "total_entries":2,
    "total_pages":1,
    "current_page":1,
    "next_page":null,
    "previous_page":null,
    "per_page":20
  },
  "requirements":[{
    "id":1,
"requirement_number":"REQ01",
    "title":"requirement title",
"description": "Sample body content",
"position":1,
"requirement_document_id":1,
"last_saved_by_id":2,
"custom_fields": [{
"id":1,
"name":"Further details",
"value":"Some further details that should be included"
}],
    "created_at":"2014-02-26T14:33:58Z",
    "updated_at":"2014-02-26T14:33:58Z"
  },
  { .... }]
}

 

Show

Description: Get the details for a requirement.

Endpoint: <base_url>/v1/projects/{project_id}/requirement_documents/{requirement_document_id}/requirements/{id}.json

Request: GET

Formats supported: JSON

Params:

  • project_id - {Integer} The associated project ID (Required)
  • requirement_document_id - {Integer} The associated requirement document ID (Required)
  • id - {Integer} The requirement ID (Required)
  • include - {Array of Strings} The additional options to include in the response
    • Options:
      • requirement_uploads - Any files that have been uploaded and associated with the requirement (The URL's are time limited and will only be valid for a short amount of time. (roughly 30 seconds))
      • steps - Any test steps that have been associated with the given requirement

Response

{ 
....,
"last_saved_by": { .... },
"custom_fields": [
{ .... },
{ .... }
],
"requirement_uploads": [
{ .... },
{ .... }
],
"steps": [
{ .... },
{ .... }
]
}

Example ruby request

HTTParty.get('https://example.api.testlodge.com/v1/projects/1/requirement_documents/1/requirements/1.json', query: { include: ['requirement_uploads'] })

Example Response

Response code: 200

{
  "id":1,
"requirement_number":"REQ01",
  "title":"Requirement title",
"description": "The content",
"position":1,
"requirement_document_id":1,
"last_saved_by_id":2,
"last_saved_by": {
"id":2,
"firstname":"Jon",
"lastname":"Cole",
"email":"jon@example.com",
"created_at":"2014-02-26T14:33:58Z",
"updated_at":"2014-02-26T14:33:58Z"
},
"requirement_uploads": [{
"id":1,
"file_name":"image.jpg",
"content_type": "image/jpeg",
"paths": {
"original": {
"name":"original",
"geometry": null,
"url":"http://s3.amazonaws.com/path/to/image"
},
"thumbnail": {
"name":"thumbnail",
"geometry":"100x100#",
"url":"http://s3.amazonaws.com/path/to/image"
}
}
}],
"custom_fields": [{
"id":1,
"name":"Further details",
"value":"Some further details that should be included"
}],
"created_at":"2014-02-26T14:33:58Z",
  "updated_at":"2014-02-26T14:33:58Z"
}

 

Create

Description: Create a new requirement.

Endpoint: <base_url>/v1/projects/{project_id}/requirement_documents/{requirement_document_id}/requirements.json

Request: POST

Formats supported: JSON

Params:

  • project_id - {Integer} The associated project ID (Required)
  • requirement_document_id - {Integer} The associated requirement document ID (Required)
  • requirement:
    • title - {String} The requirement title (Required)
    • description - {Text} The body text
    • custom_fields:

Response

{ 
....,
"last_saved_by": { .... },
"custom_fields": [
{ .... },
{ .... }
]
}

Example ruby request

HTTParty.post('https://example.api.testlodge.com/v1/projects/1/requirement_documents/1/requirements.json', body: { 
requirement: {
  title: 'Title',
   description: 'The body text',
custom_fields: {
field_1: 'Some further details that should be included'
}
  }
})

Example Response

Response code: 201

{
  "id":1,
"requirement_number":"REQ01",
  "title":"Title",
"description": "The body text",
"position":1,
"requirement_document_id":1,
"last_saved_by_id":2,
"last_saved_by": {
"id":2,
"firstname":"Jon",
"lastname":"Cole",
"email":"jon@example.com",
"created_at":"2014-02-26T14:33:58Z",
"updated_at":"2014-02-26T14:33:58Z"
},
"custom_fields": [{
"id":1,
"name":"Further details",
"value":"Some further details that should be included"
}],
"created_at":"2014-02-26T14:33:58Z",
  "updated_at":"2014-02-26T14:33:58Z"
}

 

Update

Description: Update a requirement.

Endpoint: <base_url>/v1/projects/{project_id}/requirement_documents/{requirement_document_id}/requirements/{id}.json

Request: PATCH

Formats supported: JSON

Params:

  • project_id - {Integer} The associated project ID (Required)
  • requirement_document_id - {Integer} The associated requirement document ID (Required)
  • id - {Integer} The requirement ID (Required)
  • requirement:
    • title - {String} The requirement title
    • description - {Text} The body text
    • custom_fields:

Response

{ 
....,
"last_saved_by": { .... },
"custom_fields": [
{ .... },
{ .... }
]
}

Example ruby request

HTTParty.patch('https://example.api.testlodge.com/v1/projects/1/requirement_documents/1/requirements/1.json', body: { 
requirement: {
  title: 'New name'
  }
})

Example Response

Response code: 200

{
  "id":1,
"requirement_number":"REQ01",
  "title":"New name",
"description": "The body text",
"position":1,
"requirement_document_id":1,
"last_saved_by_id":2,
"last_saved_by": {
"id":2,
"firstname":"Jon",
"lastname":"Cole",
"email":"jon@example.com",
"created_at":"2014-02-26T14:33:58Z",
"updated_at":"2014-02-26T14:33:58Z"
},
"custom_fields": [{
"id":1,
"name":"Further details",
"value":"Some further details that should be included"
}],
"created_at":"2014-02-26T14:33:58Z",
  "updated_at":"2014-02-26T14:33:58Z"
}

 

Delete

Description: Delete a requirement.

Endpoint: <base_url>/v1/projects/{project_id}/requirement_documents/{requirement_document_id}/requirements/{id}.json

Request: DELETE

Formats supported: JSON

Params:

  • project_id - {Integer} The associated project ID (Required)
  • requirement_document_id - {Integer} The associated requirement document ID (Required)
  • id - {Integer} The requirement ID (Required)

Response

{ }

Example ruby request

HTTParty.delete('https://example.api.testlodge.com/v1/projects/1/requirement_documents/1/requirements/1.json')

Example Response

Response code: 204

{ }
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.