Welcome to easeRequirements – Requirements Management for Jira’s REST API 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 easeRequirements 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.

URI Structure

All the easeRequirements endpoints can be accessed via URI paths with the following structure:
https://{server_location}.r4j-cloud.easesolutions.com/rest/api/1/<resource-path>

On the other hand, the URI path for Jira APIs would be:
https://<host>/rest/api/<version>/<resource-path>

Authentication

To access the easeRequirements REST API, there are 2 possible options. You can learn more about JWT auth for Connect apps REST API here.

1. Or you can use your email address and Jira token as credentials for basic authentication. Please take note of the additional header information needed “X-Atlassian-Base-Url“ where you need to specify your Jira Cloud base URL. Syntax:

2. You can create an easeRequirements API Token and use it directly in the Authorization Header. It’s important to indicate that it’s a JWT Token. Example:

Methods and Parameters

HTTP methods

The easeRequirements 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 Parameters

The request and response for an endpoint is always a single JSON object.

Path Parameters

Since easeRequirements 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 the following path:
https://{server_location}.r4j-cloud.easesolutions.com/rest/api/1/tree/projects/{projectKey}/items/{idOrJiraIssueKey}

In this example, projects are the primary resource with the sub-resource items, both being collection resources. To identify a single resource for each, a resource identifier must be provided through the path parameters {projectKey} and {idOrJiraIssueKey} consecutively. When replacing the identifiers with actual data, your final request URL will be:
https://{server_location}.r4j-cloud.easesolutions.com/rest/api/1/tree/projects/ABC/items/ABC-100

Query String Parameters

The query parameters are mostly used for pagination, filtering, and toggles with boolean values.

When query parameters are used to input values, they are validated to accept a maximum of 100 parameters.
(This applies currently only to the DELETE endpoint.)

Request Body Parameters

POST and PUT requests may require you to include a request body in JSON format.

The easeRequirements Cloud REST API Reference provides the details for request and response structures for each endpoint.

Parameter Guidelines

Jira and easeRequirements references

All parameters that pertain to Jira identifiers are prefixed with “jira” (e.g.: jiraIssueKey, jiraIssueId, jiraProjectId).
Identifiers not prefixed with “jira” reference easeRequirements entities (e.g.: id refers to the id of an item or folder in the tree).

Mutually exclusive parameters

Some methods may include different ways to reference an entity, for instance when adding an item to the tree you can specify the jiraIssueId or the jiraIssueKey. You don't need to specify both, it is either one or the other.

Pagination

The REST API uses pagination to improve performance. Pagination is enforced for operations that could return a large collection of items. When you make a request to a paginated resource, the response wraps the returned array of values in a JSON object with paging metadata.

• startAt is the index of the first item returned in the page.

• maxResults is the maximum number of items that a page can return. Each operation can have a different limit for the number of items returned, and these limits may change without notice. To find the maximum number of items that an operation could return, set maxResults to a large number—for example, over 1000—and if the returned value of maxResults is less than the requested value, the returned value is the maximum.

• total is the total number of items contained in all pages. This number may change as the client requests the subsequent pages, therefore the client should always assume that the requested page can be empty. Note that this property is not returned for all operations.

• isLast indicates whether the page returned is the last one. Note that this property is not returned for all operations.

Response Status Codes

The app 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 easeRequirements 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: