REST API 2.0

Welcome to R4J – Requirements 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 R4J. Looking for the REST API reference for R4J’s REST API 1.0? Find them here.

Using R4J 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.requirements/2.0/resource-path

Methods and Parameters

HTTP methods

The R4J 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/REQ4J/pages/1473937542 provides the details for request and response structures for each endpoint.

Path Parameters

Since R4J’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.requirements/2.0/projects/{projectKey}/folders/{id}

In this example, projects is the primary resource with the sub-resource 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.requirements/2.0/projects/ABCD/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

R4J 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 R4J 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.
Hint: R4J endpoints accept request data in JSON 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:

1 2 3 { "message": "Reason for request failure here." }