BDD Content API
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
See 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).
|
|
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.
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.
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.