BDD Content API

Applies to Zephyr Squad Cloud, last modified on February 10, 2022

Gherkin content of BDD Features and Scenarios in Zephyr Squad Cloud is accessible via a REST API. You can use the API to get and set feature content and scenario content programmatically.

API overview

Authentication

Considerations

The API lets you get and set the following content:

  • For BDD Features - their Background content.

  • For BDD Scenarios - the scenario content (steps, examples, and so on).

Feature-level content accessible via API

Click the image to enlarge it.

Scenario-level content accessible via API

Click the image to enlarge it.

This API works with existing BDD Features and Scenarios in your Jira Cloud instance. You can use the Jira Cloud REST API to get a list of existing BDD Features and Scenarios. BDD Features are Story-type issues with the BDD_Feature label, and BDD Scenarios are Test issues with the BDD_Scenario label.

If you want to create a new BDD Feature or Scenario from scratch, you need to use the Jira API first to create a new issue with the appropriate type and label. Then you can use the Zephyr API described here to add Gherkin content for that Feature or Scenario.

Issue IDs

The API uses Jira issue IDs which are different from issue keys (such as ABC-123). You can get the issue IDs in several ways.

  1. Open the issue whose ID you are looking for.

  2. Switch to the old issue view by selecting See the old view from the actions list:

    Switching to the old Jira issue view

    Click the image to enlarge it.

  3. Hover over the Edit button. The ID will be displayed in a tooltip at the bottom of the browser window. In this example, the ID is 10019.

    Issue ID in a tooltip

    Click the image to enlarge it.

While logged into Jira, paste the following into the browser address bar replacing the highlighted values with yours:

https://YOUR_SUBDOMAIN.atlassian.net/rest/api/3/issue/ABC-1234?fields=id

Look for the id in the returned data:

{"expand":"renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations","id":"1150196","self":"https://YOUR_SUBDOMAIN.atlassian.net/rest/api/3/issue/1150196","key":"ABC-1234"}

You can use the Jira Cloud REST API to get a list of all BDD Features and Scenarios in a project, including their IDs.

GET URL to search for Features:

https://YOUR_SUBDOMAIN.atlassian.net/rest/api/3/search?jql=project=ABC%20and%20issueType=Story%20and%20labels=BDD_Feature&fields=id&maxResults=100

GET URL to search for Scenarios:

GET https://YOUR_SUBDOMAIN.atlassian.net/rest/api/3/search?jql=project=ABC%20and%20issueType=Test%20and%20labels=BDD_Scenario&fields=id&maxResults=100

See the Jira Cloud REST API documentation for details.

Get feature/scenario content

Use this to get Gherkin content of a feature’s Background or a scenario. The response also includes the date and time when the specified feature or scenario was created and last updated.

Request URL

GET https://prod-api.zephyr4jiracloud.com/connect/public/rest/api/1.0/integration/bddcontent/<issue_id>

where <issue_id> is a numeric issue ID, for example, 10000. The specified issue must be a Zephyr BDD Feature or Scenario (see Considerations).

Response body

A successful request returns a response body like this:

{
  "data": {
    "id": 10000,
    "type": "issue",
    "attributes": {
      "content": "Given a web browser is on the Google page\r\nWhen the search phrase \"apples\" is entered\r\nThen results for \"apples\" are shown",
      "created_at": "2021-07-16T15:49:04-07:00",
      "updated_at": "2021-11-22T19:05:21-07:00"
    }
  }
}

Status codes

200, body contains the data key - Successful request.

200, body contains invalid_issue - The specified issue ID was not found, or that issue does not have the BDD_Feature or BDD_Scenario label.

400, 401, 403 - The authentication headers are missing, incomplete, or invalid. For example, the JWT token is invalid or has expired.

Update feature/scenario content

This operation replaces a feature’s Background or a scenario’s content with the content provided in the request body. Note that changing a feature’s Background does not affect the content of that feature’s scenarios.

A sample use case would be to GET the existing content first, modify the text (for example, find and replace some words), then POST it back.

Request URL

POST https://prod-api.zephyr4jiracloud.com/connect/public/rest/api/1.0/integration/bddcontent/<issue_id>

where <issue_id> is a numeric issue ID, for example, 10000. The specified issue must be a Zephyr BDD Feature or Scenario (see Considerations).

You can also use the PUT method instead of POST.

Request headers

In addition to the authentication headers, the request must include:

Content-Type: application/json

Request body

{
  "content": "Gherkin content"
}

where content is a JSON string containing a Gherkin scenario or a feature background. New lines must be encoded as \n or \r\n, and other characters that have special meaning in JSON strings must be escaped accordingly.

For example, this Gherkin scenario:

Given a web browser is on the Google page
When the search phrase "apples" is entered
Then results for "apples" are shown

is represented as follows:

{
  "content": "Given a web browser is on the Google page\r\nWhen the search phrase \"apples\" is entered\r\nThen results for \"apples\" are shown"
}

Response body

A successful request returns a response body like this:

{
  "data": {
    "id": 10000,
    "type": "issue",
    "attributes": {
      "content": "Given a web browser is on the Google page\r\nWhen the search phrase \"apples\" is entered\r\nThen results for \"apples\" are shown",
      "created_at": "2021-07-16T15:49:04-07:00",
      "updated_at": "2021-11-22T19:05:21-07:00"
    }
  }
}

Status codes

200, body contains the data key - The content of a Feature or Scenario has been updated successfully.

200, body contains invalid_issue - The specified issue ID was not found, or that issue does not have the BDD_Feature or BDD_Scenario label.

400 - Bad request. Make sure the request body is valid JSON in the expected format.

The 400 status is sometimes also returned for issues with the JWT token.

401, 403 - The authentication headers are missing, incomplete, or invalid. For example, the JWT token is invalid or has expired.

422, body contains save_error - Could not update Gherkin content in the specified issue.

Delete feature/scenario content

Use this to delete a feature’s Background or delete a scenario’s content. This effectively sets the content to an empty string. The Jira issue itself is not deleted. Deleting a feature’s Background does not affect the content of that feature’s scenarios.

Request URL

DELETE https://prod-api.zephyr4jiracloud.com/connect/public/rest/api/1.0/integration/bddcontent/<issue_id>

where <issue_id> is a numeric issue ID, for example, 10000. The specified issue must be a Zephyr BDD Feature or Scenario (see Considerations).

Response body

A successful request returns a response body like this:

{
  "data": {
    "id": 10000,
    "type": "issue",
    "attributes": {
      "content": "",
      "created_at": "2021-07-16T15:49:04-07:00",
      "updated_at": "2021-11-22T19:05:21-07:00"
    }
  }
}

Status codes

200, body contains the data key - The content was deleted successfully.

200, body contains invalid_issue - The specified issue ID was not found, or that issue does not have the BDD_Feature or BDD_Scenario label.

400, 401, 403 - The authentication headers are missing, incomplete, or invalid. For example, the JWT token is invalid or has expired.

422, body contains save_error - Could not delete Gherkin content.

See Also

Zephyr Squad Cloud REST API
BDD Tests

Highlight search results