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.

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:

R4J: http://<host>:<port>/rest/com.easesolutions.jira.plugins.requirements/2.0/resource-path

Coverage: http://<host>:<port>/rest/com.easesolutions.jira.plugins.coverage/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 REST API 2.0 Reference 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.

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: