Articles in this section

API - Requirements

Scott Sherwood
Updated

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>/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://api.testlodge.com/v1/account/1/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>/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://api.testlodge.com/v1/account/1/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>/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://api.testlodge.com/v1/account/1/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>/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://api.testlodge.com/v1/account/1/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>/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

empty

Example ruby request

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

Example Response

Response code: 204

empty
Was this article helpful?
0 out of 0 found this helpful