How do you create a cross-reference from one Confluence page to another using REST?

Question

I'm trying to publish a bunch of automatically generated pages to Confluence using REST. The pages contain cross-references to one another, which are simple tags for which I'm currently taking a wild guess at the URL based on the target name ("http://confluence.url/display/[space]/[name]" or something with the identifier).

There are a few disadvantages with this:

• I'm taking a guess at the URL, which involves code logic where I don't want it
• The URL that I'm guessing at may change when an addon like Scroll Viewport is activated
• The system may not be able to differentiate between a hyperlink (page-to-external) and cross reference (page-to-page), eg. for detecting undefined or orphaned pages.

I'm looking for a way to create a proper cross reference from one page to another while creating/updating those pages via REST. I've tried:

• Regular HTML hyperlink to the page URL that I'm guessing, not desired for the reasons described above.
• Using a "[Link text|link+target]" syntax, this simply renders the square brackets to the page and does not create a reference
• Finding a macro to use, but it appears there is no macro for this. The Anchors macro is not what I'm looking for since that would only work for link targets within the same page.

I think I would be able to resolve all the required page ID's beforehand. Also, macros seem to be supported by REST, so a macro for cross references seems ideal.

Answer 1

I found an answer to my own question:

<ac:link>
    <ri:page ri:content-title="TheNameOfMyPage" />
    <ac:plain-text-link-body>Link text</ac:plain-text-link-body>
</ac:link>

https://community.atlassian.com/t5/Confluence-questions/How-to-insert-link-to-page-in-other-space-in-user-macro/qaq-p/582753

Update: The ac:link macro is documented more formally here: https://confluence.atlassian.com/conf51/confluence-storage-format-336169254.html