Tutorial - Create a page in Confluence with requirements using REST API
This tutorial explains how to create requirements using Confluence API.
Long story short, you just need to create a page through Confluence’s native API, with the requirement macro in it. Requirement Yogi will work its magic and automatically index the page (We’re wired on the creation/update events).
No call to Requirement Yogi is necessary.
Pre-Requisites
Generate a token in your Confluence Profile
Connect to your Confluence
Click on your profile image > Profile
In tab Settings, access Personal Access Tokens
Create token
Keep the token for later
Determine your confluence base URL
URL may look like
http://{hostname}:{port}/confluence/display/spacekey/pagename
⇒ The base URL is http://{hostname}:{port}/confluence
Create a page with a requirement macro
You must have the permission to create a page in the space
TLDR: CURL of an example request
curl --location 'http://c8.5.8.local:2001/confluence/rest/api/content' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ...' \
--header 'Cookie: JSESSIONID=...' \
--data '{
"type": "page",
"title": "Rest api creating my requirements",
"space": {
"key": "Yogi"
},
"body": {
"storage": {
"value": "<table class='\''wrapped'\''><colgroup><col /><col /><col /><col /><col /></colgroup><tbody><tr><th scope='\''col'\''>Key</th><th scope='\''col'\''>Description</th><th scope='\''col'\''>Status</th><th scope='\''col'\''>Links to other requirements in other space or not</th><th scope='\''col'\''>Links to JIRA</th></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-001</ac:parameter></ac:structured-macro></p></div></td><td>Requirement description for rest api 001</td><td>In Progress</td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\''><ac:parameter ac:name='\''spaceKey'\''>BULK</ac:parameter><ac:parameter ac:name='\''freetext'\''>Link</ac:parameter><ac:parameter ac:name='\''type'\''>LINK</ac:parameter><ac:parameter ac:name='\''key'\''>SYD-1988</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''jira'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''server'\''>Jira</ac:parameter><ac:parameter ac:name='\''serverId'\''>93399b7f-4f2b-3b2a-a949-275c7925e37c</ac:parameter><ac:parameter ac:name='\''key'\''>YOGI-10</ac:parameter></ac:structured-macro></p></div></td></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-002</ac:parameter></ac:structured-macro></p></div></td><td>N/A</td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''status'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''colour'\''>Green</ac:parameter><ac:parameter ac:name='\''title'\''>Done</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''freetext'\''>Link</ac:parameter><ac:parameter ac:name='\''type'\''>LINK</ac:parameter><ac:parameter ac:name='\''key'\''>MDK_SYS_LH_1</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><br /></p></div></td></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-003</ac:parameter></ac:structured-macro></p></div></td><td><br /></td><td><br /></td><td><br /></td><td><br /></td></tr></tbody></table>",
"representation": "storage"
}
}
}
'

Created page
Check the requirement is created
…using Requirement Yogi’s REST API:
Full documentation
See also: https://developer.atlassian.com/server/confluence/rest/v923/intro/
Method:
POST
Endpoint
{your base URL}/rest/api/content
Headers
Key | Value |
---|---|
|
|
|
|
Body
{
"type": "page",
"title": "{Page title}",
"space": {
"key": "{Space key}"
},
"body": {
"storage": {
"value": "{Storage format}",
"representation": "storage"
}
}
}
{Storage format}
can be extracted from Confluence page in Storage format
Edit a page with a requirement macro
Get the page content by ID
Method:
GET
Endpoint
{your base URL}/rest/api/content/{page ID}
Headers
Key | Value |
---|---|
|
|
⇒ Find the field "number": XX
, you will need to increment that number to update the page
Example
As opposed to the other curl above which creates a page, this one edits the page, so there is a version number and no space key
curl --location --request PUT 'http://c8.5.8.local:2001/confluence/rest/api/content/7733267' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ...' \
--header 'Cookie: JSESSIONID=...' \
--data '{
"version":{
"number": {XX + 1}
},
"type": "page",
"title": "Rest api creating my requirements but with an updated name",
"body": {
"storage": {
"value": "<table class='\''wrapped'\''><colgroup><col /><col /><col /><col /><col /></colgroup><tbody><tr><th scope='\''col'\''>Key</th><th scope='\''col'\''>Description</th><th scope='\''col'\''>Status</th><th scope='\''col'\''>Links to other requirements in other space or not</th><th scope='\''col'\''>Links to JIRA</th></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-001</ac:parameter></ac:structured-macro></p></div></td><td>Requirement description for rest api 001</td><td>In Progress</td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\''><ac:parameter ac:name='\''spaceKey'\''>BULK</ac:parameter><ac:parameter ac:name='\''freetext'\''>Link</ac:parameter><ac:parameter ac:name='\''type'\''>LINK</ac:parameter><ac:parameter ac:name='\''key'\''>SYD-1988</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''jira'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''server'\''>Jira</ac:parameter><ac:parameter ac:name='\''serverId'\''>93399b7f-4f2b-3b2a-a949-275c7925e37c</ac:parameter><ac:parameter ac:name='\''key'\''>YOGI-10</ac:parameter></ac:structured-macro></p></div></td></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-002</ac:parameter></ac:structured-macro></p></div></td><td>N/A</td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''status'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''colour'\''>Green</ac:parameter><ac:parameter ac:name='\''title'\''>Done</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''freetext'\''>Link</ac:parameter><ac:parameter ac:name='\''type'\''>LINK</ac:parameter><ac:parameter ac:name='\''key'\''>MDK_SYS_LH_1</ac:parameter></ac:structured-macro></p></div></td><td><div class='\''content-wrapper'\''><p><br /></p></div></td></tr><tr><td><div class='\''content-wrapper'\''><p><ac:structured-macro ac:name='\''requirement'\'' ac:schema-version='\''1'\'' ><ac:parameter ac:name='\''type'\''>DEFINITION</ac:parameter><ac:parameter ac:name='\''key'\''>REST-003</ac:parameter></ac:structured-macro></p></div></td><td><br /></td><td><br /></td><td><br /></td><td><br /></td></tr></tbody></table>",
"representation": "storage"
}
}
}
'
References
Confluence Data Center REST API Documentation
https://developer.atlassian.com/server/confluence/rest/v923/intro/