CLOUD | DATA CENTER AND SERVER
REST API
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.
Users need to determine the easeRequirement location they are connected to.
Supported locations:
European Union - replace “{server_location}” by “eu” in URL below
United States - replace “{server_location}” by “us”
To know more about data residency, refer to https://support.atlassian.com/security-and-access-policies/docs/understand-data-residency/
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.
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:
curl -D- --basic \
-u <user_email>:<jira_api_token> \
-X GET \
-H "X-Atlassian-Base-Url:<jira_instance_base_url>" \
https://{server_location}.r4j-cloud.easesolutions.com/rest/api/1/<resource-path>
Example
curl -D- --basic \
-u my.email@company.com:ATATT3xFfGF0nPM4..dummy..IzU=455E85AF \
-X GET \
-H "X-Atlassian-Base-Url:https://mycompany.atlassian.net/" \
https://{server_location}.r4j-cloud.easesolutions.com/rest/api/1/<resource-path>
You can learn more about Basic Authentication here.
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:
curl -X GET https://{server_location}.r4j-cloud.easesolutions.com/rest/api/1/<resource-path> -H 'authorization: JWT <easeRequirements-api-token>'
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, setmaxResults
to a large number—for example, over 1000—and if the returned value ofmaxResults
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.
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. |
429 Too Many Requests | |
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:
Go to REST API 2.0 Reference >>