REST API

APIResource

@Internal Private resource. It will change often and it is not entirely documented.

GET /rest/reqs/1/api

@Internal Private resource. It will change often and it is not entirely documented.

Displays generic information about this REST resource.

Type	Name	Description
Query param	?url=...	String.
Query param	?applinkId=...	String.
Returns		HTTP Response.

POST /rest/reqs/1/api

@Internal Private resource. It will change often and it is not entirely documented.

This is the RY API v1-to-now, the one that is standard between all external apps around RY.

Type	Name	Description
Query param	?url=...	String.
Query param	?applinkId=...	String.
Query param	?timeout=...	Long. the timeout in milliseconds, minimum 3 seconds, and default is 40s
Query param	?bypassLock=...	boolean. false by default. True if you want to bypass the lock, notably if the queue is being sent by the administrator.
Body		`[ { // Object of type ConfluenceQueueMessage type: String, newHtmlExcerpt: String, newSpaceKey: String, newKey: String, newBaseline: Integer, newUrl: String, status: String, lastResponse: String, authorKey: String, authorName: String, isPublicDescription: Boolean, }, ... ]`
Returns		HTTP Response.

PUT /rest/reqs/1/api/{applinkId}/mode

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Path param	{applinkId}	String.
Body		String.
Returns		HTTP Response.

PUT /rest/reqs/1/api/{applinkId}/version

@Internal Private resource. It will change often and it is not entirely documented.

Updates the API to the provided version.

@since RY-395 in RY 2.2.1 (API v3)

Type	Name	Description
Query param	?url=...	String.
Query param	?applinkId=...	String.
Body		String. the maximum supported version on the Confluence side
Returns		HTTP Response.

IssueLinkResource

@Internal Private resource. It will change often and it is not entirely documented.

GET /rest/reqs/1/issuelinks

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Query param	?relationship=...	String.
Query param	?applink=...	String.
Query param	?spaceKey=...	String.
Query param	?reqKey=...	String.
Query param	?v=...	Long.
Returns		HTTP Response.

GET /rest/reqs/1/issuelinks/{issueKey}

@Internal Private resource. It will change often and it is not entirely documented.

List issue links.
Used by Confluence, and by the Jira panel and popups.

@since it was introduced at least before APIv5.

Type	Name	Description
Path param	{issueKey}	String. the issue
Query param	?relationship=...	String. optional, the relationship, as a filter
Query param	?fixBrokenLinks=...	boolean. boolean, Whether to fix broken links or not. This argument was introduced in the version 2.6.5 (API V9), to fix broken links and help RY Confluence move links of moved issues to new issues. If the customer is using RY (Confluence) version <= 2.6.4, he will not be able to move the links of the moved issue to the new one.
Query param	?fetchFromConfluence=...	boolean. default is false. If true, this will send requests to Confluence servers to get the latest text of the requirements.
Query param	?version=...	Integer. the api version in which the result is expected (not necessarily the one stored in the config). If >= 11, the results are in a different format.
Query param	?timeout=...	Long. the timeout in milliseconds
Returns		HTTP Response. the list of requirements (may be empty); 404 if the issue is not found or if the user doesn't have permissions.

POST /rest/reqs/1/issuelinks/{issueKey}

@Internal Private resource. It will change often and it is not entirely documented.

Create one or several links

Type	Name	Description
Path param	{issueKey}	String. the issue key
Body		list of Requirement with properties: applinkId, spaceKey, key, baselineNumber. [ { // Object of type Requirement applinkId: String, // The applink ID. It will be used to update the applinkDisplayUrl. applinkName: String, // The applink name. It's only for display applinkDisplayUrl: String, // The applink display url. It's used for display and updated sometimes. genericUrl: String, // The generic url of the requirement, relative to the target application. Example: /requirementyogi.action?req=REQ-001 spaceKey: String, // The space key. It will become part of the requirement key in the future. key: String, // The requirement key itself baselineNumber: Integer, // The version relationship: String, // Relationship to the Jira issue htmlExcerpt: String, // The HTML excerpt textExcerpt: String, // The HTML excerpt, once its text was extracted lastSynchronizationDate: { // Object of type java.util.Date }, // Date of the last synchronization with Confluence@since RY 3.1.2 properties: { // Object of type java.util.Map<java.lang.String,java.lang.String> }, // The properties, read from Confluence. Optional. Note that this field is not stored in the DB, so any object which has it comes from a direct call to Confluence.@since RY 3.1.2 and subject to change without notice. visibility: { // Object of type Visibility }, // Visibility of the requirement. The value can only be decided by Confluence, which will or will not publish the requirement's body.@since RY 3.1.0 }, ... ]
Returns		HTTP Response.

PUT /rest/reqs/1/issuelinks/{issueKey}

@Internal Private resource. It will change often and it is not entirely documented.

Reset all the links, either for a single relationship, either for all links of the issue.

Type	Name	Description
Path param	{issueKey}	String. the issue key
Query param	?relationship=...	String. the relationship. If empty, all the links of the issue will be used.
Body		list of Requirement with all their properties [ { // Object of type Requirement applinkId: String, // The applink ID. It will be used to update the applinkDisplayUrl. applinkName: String, // The applink name. It's only for display applinkDisplayUrl: String, // The applink display url. It's used for display and updated sometimes. genericUrl: String, // The generic url of the requirement, relative to the target application. Example: /requirementyogi.action?req=REQ-001 spaceKey: String, // The space key. It will become part of the requirement key in the future. key: String, // The requirement key itself baselineNumber: Integer, // The version relationship: String, // Relationship to the Jira issue htmlExcerpt: String, // The HTML excerpt textExcerpt: String, // The HTML excerpt, once its text was extracted lastSynchronizationDate: { // Object of type java.util.Date }, // Date of the last synchronization with Confluence@since RY 3.1.2 properties: { // Object of type java.util.Map<java.lang.String,java.lang.String> }, // The properties, read from Confluence. Optional. Note that this field is not stored in the DB, so any object which has it comes from a direct call to Confluence.@since RY 3.1.2 and subject to change without notice. visibility: { // Object of type Visibility }, // Visibility of the requirement. The value can only be decided by Confluence, which will or will not publish the requirement's body.@since RY 3.1.0 }, ... ]
Returns		HTTP Response.

DELETE /rest/reqs/1/issuelinks/{issueKey}

@Internal Private resource. It will change often and it is not entirely documented.

Remove the links.

Type	Name	Description
Path param	{issueKey}	String. the issue key
Body		list of Requirement with properties: applinkId, spaceKey, key, baselineNumber, relationship. [ { // Object of type Requirement applinkId: String, // The applink ID. It will be used to update the applinkDisplayUrl. applinkName: String, // The applink name. It's only for display applinkDisplayUrl: String, // The applink display url. It's used for display and updated sometimes. genericUrl: String, // The generic url of the requirement, relative to the target application. Example: /requirementyogi.action?req=REQ-001 spaceKey: String, // The space key. It will become part of the requirement key in the future. key: String, // The requirement key itself baselineNumber: Integer, // The version relationship: String, // Relationship to the Jira issue htmlExcerpt: String, // The HTML excerpt textExcerpt: String, // The HTML excerpt, once its text was extracted lastSynchronizationDate: { // Object of type java.util.Date }, // Date of the last synchronization with Confluence@since RY 3.1.2 properties: { // Object of type java.util.Map<java.lang.String,java.lang.String> }, // The properties, read from Confluence. Optional. Note that this field is not stored in the DB, so any object which has it comes from a direct call to Confluence.@since RY 3.1.2 and subject to change without notice. visibility: { // Object of type Visibility }, // Visibility of the requirement. The value can only be decided by Confluence, which will or will not publish the requirement's body.@since RY 3.1.0 }, ... ]
Returns		HTTP Response.

JiraMiscResource

The search resource for requirements

@Internal Private resource. It will change often and it is not entirely documented.

DELETE /rest/reqs/1/baselines/{project}

@Internal Private resource. It will change often and it is not entirely documented.

Clear the cache of baselines for the project

Type	Name	Description
Path param	{project}	String. project key
Returns		HTTP Response. a text answer.

GET /rest/reqs/1/baselines/{projectKey}

@Internal Private resource. It will change often and it is not entirely documented.

Search for the space and baselines according to "q".

@since 2.6.3 for the Criteria-and-baselines JS object

Type	Name	Description
Path param	{projectKey}	String.
Query param	?q=...	String. the search query
Query param	?insist=...	boolean. by default (false), we only search among baseline names for the linked spaces. If insist=true, we also search for all spaces, and all baseline names.
Query param	?limit=...	Integer.
Returns		HTTP Response.

PUT /rest/reqs/1/preferences/baselineCondition

@Internal Private resource. It will change often and it is not entirely documented.

We save the last baseline searched by the user

Type	Name	Description
Query param	?projectKey=...	String.
Body		String.
Returns		HTTP Response.

PUT /rest/reqs/1/rename

@Internal Private resource. It will change often and it is not entirely documented.

Called by Confluence.

This is a redirect to /operations/rename

@deprecated Please use {@link OperationsResource#rename} since 2.2.0/RY-395

Type	Name	Description
Query param	?url=...	String. the baseurl of Confluence
Body		a list of RequirementRenameData `[ { // Object of type AbstractResourceWithOperations.RequirementRenameData oldKey: String, spaceKey: String, version: Integer, newKey: String, newSpaceKey: String, newVersion: Integer, issueKey: String, relationship: String, }, ... ]`
Returns		HTTP Response. Always 200, with a list of error messages.

GET /rest/reqs/1/history/issue/{issueNumber}

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Path param	{issueNumber}	Long.
Query param	?from=...	Long.
Query param	?to=...	Long.
Returns		HTTP Response.

GET /rest/reqs/1/relationships

@Internal Private resource. It will change often and it is not entirely documented.

Get relationships

Type	Name	Description
Query param	?projectKey=...	String.
Returns		HTTP Response.

MetadataResource

A resource to retrieve the metadata for Requirement Yogi, such as the list of custom fields

@Internal Private resource. It will change often and it is not entirely documented.

GET /rest/reqs/1/metadata/customfields

@Internal Private resource. It will change often and it is not entirely documented.

Replaces http://jira.local:2990/jira/rest/api/2/field because it is too slow on larger instances

Type	Name	Description
Query param	?fields=...	String. comma-separated list of field IDs (customfield_10000,...) to include
Query param	?types=...	String. comma-separated list of field types (schema.custom value in /rest/api/2/field) to include
Returns		HTTP Response.

OperationsResource

In this class, we'll progressively move all operations, such as /rename and /createRIL.

@since 2.2 and the implementation of RY-395 (the big Jira refactor)

@Internal Private resource. It will change often and it is not entirely documented.

GET /rest/reqs/1/operations/{applinkId}

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Returns		HTTP Response.

PUT /rest/reqs/1/operations/{applinkId}/rename

@Internal Private resource. It will change often and it is not entirely documented.

Called by Confluence.

Type	Name	Description
Path param	{applinkId}	String.
Body		a list of RequirementRenameData `[ { // Object of type AbstractResourceWithOperations.RequirementRenameData oldKey: String, spaceKey: String, version: Integer, newKey: String, newSpaceKey: String, newVersion: Integer, issueKey: String, relationship: String, }, ... ]`
Returns		HTTP Response. Always 200, with a list of error messages.

POST /rest/reqs/1/operations/{applinkId}/issues-bulk-operation/projects/{projectId}

@Internal Private resource. It will change often and it is not entirely documented.

Create or update issues in bulk

@since APIv5 and version 2.3.

Type	Name	Description
Path param	{applinkId}	String. The application link.
Path param	{projectId}	long. The project id.
Query param	?url=...	String. Confluence url.
Query param	?issueTemplateId=...	long.
Body		List of JiraConfluenceSharedBeans.IssueRequest [ { // Object of type JiraConfluenceSharedBeans.IssueRequest requirements: [ { // Object of type JiraConfluenceSharedBeans.Requirement key: String, spaceKey: String, baseline: Integer, htmlExcerpt: String, relationship: String, isPublicDescription: Boolean, }, ... ], issueFields: [ { // Object of type JiraConfluenceSharedBeans.IssueField fieldName: String, value: String, values: [ { // Object of type java.lang.String value: [ , ... ], coder: byte, hash: int, }, ... ], }, ... ], issueKey: String, createNew: boolean, }, ... ]
Returns		HTTP Response.

GET /rest/reqs/1/operations/{applinkId}/issues-bulk-operation/jobs

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Path param	{applinkId}	String.
Returns		HTTP Response.

GET /rest/reqs/1/operations/{applinkId}/issues-bulk-operation/jobs/{jobId}

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Path param	{applinkId}	String.
Path param	{jobId}	long.
Returns		HTTP Response.

POST /rest/reqs/1/operations/{applinkId}/issues-bulk-operation/jobs/{jobId}/abort

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Path param	{jobId}	long.
Returns		HTTP Response.

DELETE /rest/reqs/1/operations/{applinkId}/issues-bulk-operation/jobs/{jobId}

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Path param	{jobId}	long.
Returns		HTTP Response.

QueueResource

@Internal Private resource. It will change often and it is not entirely documented.

GET /rest/reqs/1/queue/{applinkId}/messages

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Path param	{applinkId}	String.
Returns		HTTP Response.

POST /rest/reqs/1/queue/{applinkId}/messages

@Internal Private resource. It will change often and it is not entirely documented.

Send queue messages to an instance of Confluence.
If the user is Admin, it sends all messages, if not it sends the user's messages.

Type	Name	Description
Path param	{applinkId}	String. Confluence's application link id
Returns		HTTP Response.

DELETE /rest/reqs/1/queue/{applinkId}/messages

@Internal Private resource. It will change often and it is not entirely documented.

Delete QueueMessages.

Type	Name	Description
Path param	{applinkId}	String. Confluence application link id.
Query param	?status=...	Message status to delete. `{ // Object of type DBQueueMessage.Status }`
Returns		HTTP Response.

POST /rest/reqs/1/queue/{applinkId}/messages/{messageId}

@Internal Private resource. It will change often and it is not entirely documented.

Send one QueueMessage if the user has permissions.

Type	Name	Description
Path param	{applinkId}	String. Confluence application link id.
Path param	{messageId}	long. QueueMessage id.
Returns		HTTP Response.

DELETE /rest/reqs/1/queue/{applinkId}/messages/{messageId}

@Internal Private resource. It will change often and it is not entirely documented.

Delete one QueueMessage if the user has permissions.

Type	Name	Description
Path param	{applinkId}	String. Confluence application link id.
Path param	{messageId}	long. QueueMessage id.
Returns		HTTP Response.

POST /rest/reqs/1/queue/{applinkId}/repair-applink

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Path param	{applinkId}	String.
Body		String.
Returns		HTTP Response.

RecoverNullKeysResource

The search resource for requirements

@Internal Private resource. It will change often and it is not entirely documented.

GET /rest/reqs/1/recover-null-keys/suggest

@Internal Private resource. It will change often and it is not entirely documented.

Return suggestions for a given requirement that has lost its key (see https://playsql.atlassian.net/browse/RY-511)

Type	Name	Description
Query param	?id=...	long.
Returns		HTTP Response.

GET /rest/reqs/1/recover-null-keys/requirement

@Internal Private resource. It will change often and it is not entirely documented.

This function returns a requirement from Confluence.
It is specific to the 'recover-null-keys' screen.
See https://playsql.atlassian.net/browse/RY-511

Type	Name	Description
Query param	?applinkId=...	String.
Query param	?spaceKey=...	String.
Query param	?key=...	String.
Returns		HTTP Response.

PUT /rest/reqs/1/recover-null-keys/associate/{id}

@Internal Private resource. It will change often and it is not entirely documented.

This function reassigns a key to a requirement that has a NULL key.
See https://playsql.atlassian.net/browse/RY-511

Type	Name	Description
Path param	{id}	long.
Query param	?spaceKey=...	String.
Query param	?key=...	String.
Returns		HTTP Response.

SearchResource

A resource to search for requirements in Confluence.

@Internal Private resource. It will change often and it is not entirely documented.

GET /rest/reqs/1/search

@Internal Private resource. It will change often and it is not entirely documented.

Search for requirements across all applinked Confluence instances.
Permissions: Everyone can use this REST resource, so everyone can look up RY/Confluence
requirements using Jira's REST endpoint.

Type	Name	Description
Query param	?q=...	String. full-string query
Query param	?project=...	String. the current project key, optional, to restrict the query to Confluence instances and spaces which are linked with this Jira project
Query param	?spaceKey=...	String. the space key, comma-separated list
Query param	?baselineCondition=...	String.
Returns		HTTP Response. a SearchResults instance

SettingsResource

@Internal Private resource. It will change often and it is not entirely documented.

POST /rest/reqs/1/settings/{serviceId}/authenticate-user

@Internal Private resource. It will change often and it is not entirely documented.

Attempts to authenticat the user to Confluence.

Type	Name	Description
Path param	{serviceId}	String.
Body		String.
Returns		HTTP Response. an AuthenticationResponse containing the success/error messages, or a BAD_REQUEST/FORBIDDEN if Confluence wasn't even reached.

POST /rest/reqs/1/settings/{serviceId}/set-remote-user

@Internal Private resource. It will change often and it is not entirely documented.

Attempts to set the remote username for the connection

Type	Name	Description
Path param	{serviceId}	String.
Body		String.
Returns		HTTP Response. an AuthenticationResponse containing the success/error messages, or a BAD_REQUEST/FORBIDDEN if Confluence wasn't even reached.

SyncResource

Resource to manage the job that resynchronizes a set of issues with Confluence.

@Internal Private resource. It will change often and it is not entirely documented.

GET /rest/reqs/1/sync/create-random-data

@Internal Private resource. It will change often and it is not entirely documented.

Not public. Creates demo data to test the Remote Issue Link migration.

Type	Name	Description
Returns		HTTP Response.

GET /rest/reqs/1/sync/create-random-issues

@Internal Private resource. It will change often and it is not entirely documented.

Not public. Creates demo data to test the Remote Issue Link migration.

Type	Name	Description
Returns		HTTP Response.

GET /rest/reqs/1/sync

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Query param	?issues=...	String.
Returns		HTTP Response.

PUT /rest/reqs/1/sync

@Internal Private resource. It will change often and it is not entirely documented.

Resynchronizes the issue keys with Confluence:

Reads their HtmlExcerpt from Confluence
Sends to Confluence ALL the links to ALL requirements linked to these issues.

The second point means if a requirement is linked to JRA-1 and JRA-2, then the link of the requirement to JRA-2
will also be sent. It will not send links between JRA-2 and another requirement.

Type	Name	Description
Query param	?issues=...	String.
Returns		HTTP Response.

GET /rest/reqs/1/sync/job/{jobId}

@Internal Private resource. It will change often and it is not entirely documented.

Not public

Type	Name	Description
Path param	{jobId}	String.
Returns		HTTP Response.

POST /rest/reqs/1/sync/updatebaseline2

@Internal Private resource. It will change often and it is not entirely documented.

Upgrade the requirements in a baseline.

Type	Name	Description
Query param	?issue=...	String.
Body		String. a map of RYGlobalId -> Requirement.
Returns		HTTP Response. a json of the list of updated requirements and errors

REST API

REST APIs for Requirement Yogi - Jira Integration

APIResource

IssueLinkResource

JiraMiscResource

MetadataResource

OperationsResource

QueueResource

RecoverNullKeysResource

SearchResource

SettingsResource

SyncResource