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

JSON

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"
    }
  }
}
'

In body storage value, here is the HTML beautified

HTML

<table>
  <tbody>
    <tr>
      <th>Key</th>
      <th>Description</th>
      <th>Status</th>
      <th>Links to other requirements in other space or not</th>
      <th>Links to JIRA</th>
    </tr>
    <tr>
      <td>
        <div>
          <p>
            <ac:structured-macro ac:name='requirement'>
              <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>
        <div class='content-wrapper'>
          <p>
            <ac:structured-macro ac:name='status'>
              <ac:parameter ac:name='colour'>Green</ac:parameter>
              <ac:parameter ac:name='title'>Done</ac:parameter>
            </ac:structured-macro>
          </p>
        </div>
      </td>
      <td>
        <div>
          <p>
            <ac:structured-macro ac:name='requirement'>
              <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>
          <p>
            <ac:structured-macro ac:name='jira'>
              <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>
  </tbody>
</table>

Check the requirement is created

…using Requirement Yogi’s REST API:

Open this section to view the Requirement Yogi REST API

The URL is:

CODE

{your base URL}/rest/reqs/1/requirement2/spacekey?expand=all&q=page=pageid

For example:

CODE

curl --location --request GET 'http://c8.5.8.local:2001/confluence/rest/reqs/1/requirement2/Yogi?expand=all&q=page=7733267' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ...' \
    --header 'Cookie: JSESSIONID=...'

Returns:

CODE

{
    "count": 400,
    "expandable": "properties.propertyNameMeta,validations,all",
    "explanation": "Requirements defined on page 360482 and with status  'ACTIVE'",
    "limit": 600,
    "offset": 0,
    "results":
        [{
            "key": "REST-001",
            "destinationUrl": "http://c9.4.0.local:2013/c-app/spaces/TEAM/pages/360482/Page+-+ACT-1201#req-REST-001",
            "genericUrl": "/requirements/Yogi/REST-001",
            "htmlExcerpt": "RNs",
            "htmlNeedsUpdating": false,
            "id": 695,
            "isPublicDescription": false,
            "issues": [],
            "origin": {
                "pageId": 360482,
                "title": "Page - ACT-1201",
                "type": "page",
                "url": "http://c9.4.0.local:2013/c-app/spaces/TEAM/pages/360482/Page+-+ACT-1201#req-ACT-1000"
            },
            "properties": [{
                "key": "Description",
                "dataType": "STRING",
                "type": "INLINE",
                "value": "RNs"
            }, {
                "key": "Property1",
                "dataType": "STRING",
                "type": "INLINE",
                "value": "Value 1"
            }],
            "spaceKey": "TEAM",
            "status": "ACTIVE"
        },
            ...
        ]
}

Full documentation

Method: POST
Endpoint

{your base URL}/rest/api/content

Headers

Key	Value
`Authorization`	`Bearer {token}`
`Content-Type`	`application/json`

Body

JSON

 {
      "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
`Authorization`	`Bearer {token}`

⇒ 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

JSON

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"
        }
      }
    }
    '

Tutorial - Create a page in Confluence with requirements using REST API

Pre-Requisites

Generate a token in your Confluence Profile

Determine your confluence base URL

Create a page with a requirement macro

TLDR: CURL of an example request

Check the requirement is created

Full documentation

Edit a page with a requirement macro

Get the page content by ID

Example

References

Confluence Data Center REST API Documentation

Requirement Yogi REST API Documentation