REST API 2.0
Welcome to T4J – Test Management for Jira’s REST API 2.0 documentation! Here you will find the resources that will enable you to access the functionality of the plugin programmatically and allow integration and interaction across applications.
While we’re continuing support for version 1.0, we have created version 2.0 to provide a more complete and better structured REST API support for T4J.
Looking for the REST API reference for T4J’s REST API 1.0? Find them here.
Using T4J REST API
To start using the REST API, your application first needs to be authenticated by your Jira instance for your requests to go through.
After this, your application can begin to make HTTP requests to the available endpoints and manipulate the return JSON based on how you want to use the data.
Authentication
To access the REST API, the application needs to be authenticated by your Jira instance. The REST API supports the same authentication methods JIRA does.
Although, as mentioned in Jira’s API documentations:
The preferred authentication methods for the Jira REST APIs are OAuth and HTTP basic authentication (when using SSL).
Further examples regarding the different authentication methods can be found within the Jira REST API Tutorials.
URI Structure
All the endpoints can be accessed via URI paths with the following structure:http://<host>:<port>/rest/com.easesolutions.jira.plugins.testmanagement/2.0/resource-path
Methods and Parameters
HTTP methods
The T4J REST API 2.0 accepts the standard HTTP methods: GET, POST, PUT, and DELETE
Retrieve data by making a GET request.
Create a new resource through a post request.
Make a PUT request to update a resource.
Make a DELETE request to remove a resource.
Request and Response Body Parameters
The request and response for an endpoint is always a single JSON object.
POST and PUT requests may require you to include a request body in JSON format.
The https://easesolutions.atlassian.net/wiki/spaces/T4J/pages/2238906634 provides the details for request and response structures for each endpoint.
Path Parameters
Since T4J’s components are tied to Jira projects and issues, you will find that a lot of paths are structured with either a project key or an issue key. The resource identifier placeholders are indicated in curly brackets and need to be replaced with real values.
The paths are structured based on REST API naming conventions. Let’s take on the following path:http://myjirainstance.com/rest/com.easesolutions.jira.plugins.testmanagement/2.0/projects/{projectKey}/definitions/folders/{id}
In this example, projects is the primary resource with the sub-resource definitions/folders, both being collection resources. To identify a single resource for each, a resource identifier must be provided through the path parameters {projectKey} and {id} consecutively. When replacing the identifiers with actual data, your final request URL will be:http://myjirainstance.com/rest/com.easesolutions.jira.plugins.testmanagement/2.0/projects/ABCD/definitions/folders/123
Query String Parameters
The use of query string parameters has been minimized. However, when they are used, they are optional and are provided with a default. The query parameters are used for pagination, filtering, and toggles with boolean values for specific endpoints only.
Response Status Codes
T4J uses conventional HTTP response codes to indicate the success or failure of an API request. Generally, HTTP codes in the range of 2xx indicates a successful request while codes in the range of 4xx indicates a failed request. Failed requests will usually include messages descriptive of the cause of the error. Finally, codes in the range of 5xx indicates application/server errors.
Below is a summary of the possible response status codes for T4J REST APIs.
Status Code | Description |
200 OK | Everything worked as expected. Response data is returned. |
201 Created | The requested resource was created successfully. Response data is returned. |
204 no content | Everything worked as expected. No response data is provided. |
400 bad request | The request was not accepted (often caused by missing a required parameter). |
401 unauthorized | Username or password authentication failed or no permission to perform request. |
403 forbidden | License is invalid or expired or Jira version is incompatible. |
404 not found | The requested resource does not exist. |
409 conflict | There is a conflict with the processed resource. |
415 unsupported media type | The server cannot accept the request because the payload format is in an unsupported format. |
500 internal server error | Something went wrong (either with Jira or the application). |
The HTTP code returns in the range of 4xx and 5xx will always include a JSON return with the relevant error message in the following format:
{
"message": "Reason for request failure here."
}