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.
See Authentication.
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).
|
|
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.
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.
Open the issue whose ID you are looking for.
Switch to the old issue view by selecting See the old view from the actions list:
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.
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.
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.
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).
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"
}
}
}
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.
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.
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
.
In addition to the authentication headers, the request must include:
Content-Type: application/json
{
"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"
}
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"
}
}
}
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.
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.
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).
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"
}
}
}
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.