Breadcrumbs

REST API (Data Center)

🚀

New! REST API documentation using SWAGGER on your own instance!

🌟

Looking for the Requirement Yogi Cloud API?

We use Swagger and Open API : REST APIs (Cloud)

đź“Ś

Experimental API

Our API is subject to changes.

  • When we annotate @Public, we attempt with "best effort" to keep the API backwards-compatible for as long as possible.

    • If we want to deprecate, we will annotate with @Deprecated for a few versions, then remove it in the major version (in "platform.major.micro" versioning scheme, for example in 2.2.0).

    • We may add parameters, not remove them.

  • When we annotate @Internal, we don't even try to keep it stable, it usually changes from 1 micro version to another. Those APIs are tightly couples with the Javascript.

  • When we don't annotate, please consider it as @Internal.

This documentation is only designed for programmers. It is provided as is, and programmers are expected to be good enough to solve problems.

Use our Open API / Swagger UIs

Files in the format of Open API v3 (formerly Swagger v2) describe all REST APIs that are accessible for users in an application. The software offers:

  • A UI where you can try out the APIs,

  • A “openapi.json” file which fully describes the documentation of each REST API route.

image-20250410-135113.png

The URLs for those files will be:

http://your-confluence-url/requirementyogi/swaggerui.action
http://your-confluence-url/rest/reqs/1/openapi
http://your-jira-url/secure/admin/swaggerui!default.jspa
http://your-jira-url/rest/reqs/1/openapi

REST API in Confluence

Base URL

The "base URL" is the address of Confluence. It could be:

  • https://confluence.example.com if there is no port, no context path and it's https.

  • http://confluence.example.com:8090/confluence if there is a port, a context path and http.

Try with {baseUrl}/admin/viewgeneralconfig.action to ensure you have the right one. In the following documentation, we will omit the base URL.

REST Resources in Confluence

Verb and URL

Comments and query string arguments

GET /rest/reqs/1/requirement2/{spaceKey}

Search for requirements.

  • q = The query, using the Search Syntax.

  • spaceKey = The scope of the search. This is different from the spaceKey in the GET path. If the spaceKey in the query string isn't provided, and if the "Isolate Spaces" option is ticked in the Requirement Yogi administration, then the search will be restricted by default to the spaceKey provided in the GET path; Otherwise the spaceKey provided in the GET path has no effect.

  • offset = The pagination offset

  • limit = The pagination limit

  • order = The SQL ORDER BY clause (by default: "REQKEY ASC, BASELINE DESC")

  • includeArchived = true / false whether the archived requirements should be included. Otherwise, only current (ACTIVE) requirements are displayed.

  • baselineCondition = Do not use.

  • suggest = Do not use.

  • expand = Properties that you need to be loaded. Can use all to get everything (⚠️ request may be slow)

POST /rest/reqs/1/requirement2/{spaceKey}

Do not use.

PUT /rest/reqs/1/requirement2/{spaceKey}

Do not use.

GET /rest/reqs/1/requirement2/{spaceKey}/{key}

Get a requirement.

  • v = {integer} – Return the version of the requirement in baseline 'v'

  • expand = Use "references" if references to pages need to be expanded.

POST /rest/reqs/1/requirement2/{spaceKey}/{key}

Do not use.

PUT /rest/reqs/1/requirement2/{spaceKey}/{key}

Do not use.

DELETE /rest/reqs/1/requirement2/{spaceKey}/{key}

Do not use.

GET /rest/reqs/1/requirement3

Do not use.

Baselines

GET /rest/reqs/1/baseline/{spaceKey}

Get the list of baselines in this space.

  • expand: Use "details" if you need to get the link to the baseline page and the number of requirements.

POST /rest/reqs/1/baseline/{spaceKey}/1/create

Freeze a baseline. The body must be in JSON:

JavaScript
{
    name: "The name of the baseline",
    ceo: the ID of the page which the baseline is attached to (cannot be null),
    queryString: the RY search query
}

The ceo is the baseline page. It is not the page which contains the original definition of the requirements. It can be any arbitrary page, its title will be synchronized with the name of the baseline, and if there is a Baseline macro on it, this macro will show the count of requirements.

The queryString is the list of all requirements which must be copied and archived in this baseline.

POST /rest/reqs/1/baseline/{spaceKey}/1/create-instant

Create and freeze instantly a baseline. There will be no parent page for this baseline. The body must be JSON:

JavaScript
{
    name: "The name of the baseline",
    fromCeo: the pageId of a page with requirements to freeze, cannot be null,
    fromCeoWithChildren: true/false.
}

If fromCeoWithChildren is true, the requirements of all the child pages will be baselined too.

DELETE /rest/reqs/1/baseline/{spaceKey}/{baseline}

Delete a baseline. No JSON body.

PUT /rest/reqs/1/baseline/{spaceKey}/{baseline}/label

Change the label of a baseline. Use a text/plain body.

GET /rest/reqs/1/baseline/{spaceKey}/{baseline}/pages

Returns the list of pages which have requirements of this baseline.

POST /rest/reqs/1/sync

Deprecated. Do not use.

POST /rest/reqs/1/helpers/reindex/{contentId}

Reindexes a page. It will only mark the requirements are ACTIVE/DELETED and flag them as "Needs excerpt", which means those requirements will appear with a red dot. The next time a user views the page, excerpts will be gathered and saved as the text and properties of requirements, and the red dot will disappear.

GET /rest/reqs/1/integration

Returns the list of application links and their RY configuration.

Permissions: Confluence administrators only.

  • Admins can deactivate a Jira applink in the administration of Confluence, just for Requirement Yogi,

  • Admins can choose which API version they use.

  • API versions are usually updated when a user performs a search in the Link dialog in Jira. If Jira notices that Confluence supports, say, API v4, and Jira does too, then it will upgrade to the maximum supported by both.

POST /rest/reqs/1/integration

Create an integration. Don't do it.

Permissions: Confluence administrators only.

GET /rest/reqs/1/integration/{serviceId}

Returns the details of the integration:

IntegrationDescriptor
JavaScript
{
    serviceId: the applink id or the internal UUID for this integration,
    applinkId: same as serviceId, if it is an application link,
    label: the name of the instance (ex: "Customer support Jira"),
    displayUrl: Jira's URL,
    rpcUrl: Jira's backend URL,
    endpoint: the address of the Requirement Yogi endpoints inside of Jira. It is empty for v0, has a value for v1 and above. It would only vary if a person programmed a new endpoint for, say, BitBucket Server or Dassault Catia,
    sendErrorsToEmail: the email API errors are sent to,
    sendErrorsToEmailThrottle: the throttle between sending each API error email,
    userKey: the user to connect to Jira,
    username: for information only, the login of the user,
    version: the API version to use,
    countMessagesInQueue: the count of messages currently NEW in the queue,
    status: "ACTIVE" or "DISABLED"
}


Permissions: Confluence administrators only.

PUT /rest/reqs/1/integration/{serviceId}

Updates the descriptor.

Permissions: Confluence administrators only.

GET /rest/reqs/1/integration/{serviceId}/queue/outbound?limit=50

Get the list of messages which will be sent to Jira in the next synchronization (every 3 mintues):

  • serviceId: The applink id, or the internal UUID,

  • limit: The maximum number of messages to return,

  • includeDone: true/false,

  • includeLastRespnse: true/false

PUT /rest/reqs/1/integration/{serviceId}/queue/outbound/{messageId}

PUT sends this item to Jira. No body necessary.

DELETE removes this message from the list.


REST API in Jira

Verb and URL

Comments and query string arguments

GET /rest/reqs/1/api

Displays generic information about this REST resource. Also displays the current user's name.

  • ?applinkId={the applink id}

  • ?url={the applink url}

  • Both arguments above display whether the Applink was recognized.

Anonymous-allowed.

POST /rest/reqs/1/api

Posts messages from Confluence to Jira.

Messages are encoded in JSON:

Queue message, APIv4 
{
	id: an arbitrary integer, local to this request,
    type: "UPDATED" or "DELETED" or "MOVED" or "LINK",
    // If the message is sent using a technical user, this contains
    // the Confluence author details
    authorKey, authorName,
    
    // Related to the Confluence requirement
    spaceKey, key, baseline,
    
    // Related to the Jira issue
    estate: "_", // Always "_" for Jira,
    objectKey: "the issue key"
    
    // Related to both
    relationship,

    // Data
    newHtmlExcerpt,
    newSpaceKey,
    newKey,
    newBaseline,
    newUrl
}


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

Changes the API mode. The body must be a string between quotes: AUTO, MANUAL, DISABLED, sent with a JSON content type.

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

Changes the API version. The body is an integer, sent with a JSON content type.

The API changes the version and tells the user which version was accepted (in case Jira doesn't support that version).

GET /rest/reqs/1/issuelinks

Not implemented, returns a fixed string.

GET /rest/reqs/1/issuelinks/{issueKey} đź’ˇ

Returns the links on an issue. A ?relationship= parameter can be specified.

POST /rest/reqs/1/issuelinks/{issueKey} đź’ˇ

Creates issue links. Body is JSON:

[{
    // Primary key of the requirement in Confluence
	applinkId: the applink ID of Confluence,
    spaceKey,
    key,
    baselineNumber,
    // Part of the primary key for Jira: issue-relationship-requirement
    relationship,
    
    // More details of the requirement
    genericUrl: the URL of the requirment, relative to the baseURL of Confluence,
    htmlExcerpt: the excerpt, in HTML format. It will be sanitized, but not escaped.   
}, ...]

The HTML is updated for this requirement in Jira, which means if another Jira issue has a link to the same requirement, its text will be updated.

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

Same as POST, but removes all existing links on this issue before. Can be scoped using ?relationship=...

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

List of links to delete from this issue:

[{ applinkId, spaceKey, key, baselineNumber, relationship }, ...]


PUT /rest/reqs/1/sync?issues=PROJ-2,PROJ-1

Ask Jira to resynchronize those issues with Confluence:

  • Jira will ask Confluence for the latest HTML of the requirements,

  • Jira will tell Confluence what are the correct links between requirements and Jira issues. 

All links of all requirements linked with the specified issues are synced. It means:

  • if you synchronize JIRA-1 which has REQ-001 and REQ-002,

  • and if REQ–2 is also on JIRA-2, even though it is not in the list of synchronized requirements,

  • Then it will send the 3 relationships to Confluence.

Examples

Add a link in Jira:

curl 'http://j10.3.19.local:2030/j-app/rest/reqs/1/issuelinks/SCRUM-1' \
  -X 'POST' \
  -H 'Connection: keep-alive' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -b 'JSESSIONID=...' \
  --data-raw '[{"applinkId":"b87f691d-b781-3965-becb-fad2b5bc8175","spaceKey":"S3","key":"BR-01","relationship":"implements"}]'
# Response : {...,"status":"ok"}

Remove a link from Jira:

curl 'http://j10.3.19.local:2030/j-app/rest/reqs/1/issuelinks/SCRUM-1' \
  -X 'DELETE' \
  -H 'Connection: keep-alive' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -b 'JSESSIONID=...' \
  --data-raw '[{"applinkId":"b87f691d-b781-3965-becb-fad2b5bc8175","spaceKey":"S3","key":"BR-01","relationship":"implements"}]'
# Response : {...,"status":"ok"}

Overwrite existing links:

curl 'http://j10.3.19.local:2030/j-app/rest/reqs/1/issuelinks/SCRUM-1?relationship=implements' \
  -X 'PUT' \
  -H 'Connection: keep-alive' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -H 'Accept: application/json' \
  -b 'JSESSIONID=...;' \
 --data-raw '[{"applinkId":"b87f691d-b781-3965-becb-fad2b5bc8175","spaceKey":"S3","key":"BR-01"}]'
# Response : {...,"status":"ok"}

List the links:

curl 'http://j10.3.19.local:2030/j-app/rest/reqs/1/issuelinks/SCRUM-1?relationship=implements'

Note: The “applinkId” UUID can be found when browsing the Jira administration → Application links → Click on the line of Confluence → It’s the ID in the URL.

Note: The “baseline” argument is omitted here for simplicity.