How do the various Confluence document formats differ?

Question

I am working with the Confluence REST api, and want to extract some documents. The document body is available in several formats: editor, storage, view, export_view, anonymous_export_view,... But I have not found a description anywhere of what they are, or what each one is intended for. (This answer mentions several formats but doesn't say what they are.) In my checks, all formats have embedded HTML-style markup but with different non-standard attributes. Any pointers?

Specifically, I am looking for the best format to use for conversion to other, non-confluence formats.

Example query:

https://confuence.example.com/rest/api/content?spaceKey=doc&expand=body.editor,body.storage,body.anonymous_export_view,body.view,body.export_view&start=0&limit=50

This returns several alternative formats, and I see lots of random-seeming differences. So what's the story?

Answer 1

The best description of each of these fields that I have found is on the Java API documentation for Confluence, specifically for the ContentRepresentation class.

You may notice that some of the descriptions in the above docs are truncated. They're just document comments rendered by Javadoc, so something has gone wrong there. As it happens, I work for Atlassian Premier Support, so I've tracked down the complete document comments (yay code search) for your reading pleasure:

• ANONYMOUS_EXPORT_VIEW
  • HTML representation for viewing, but with absolute urls, instead of relative urls in the markup, and macros are rendered as though it is viewed by an anonymous user. Useful for exporting in situations where you might not want to reveal sensitive data , or you do not want to pay the cost of a permission check for the export. The output of this can be cached as long as the underlying content has not changed.
• EDITOR
  • Representation suitable for use in the rich text editor
• EXPORT_VIEW
  • HTML representation for viewing, but with absolute urls, instead of relative urls in the markup. Useful for exporting.
• PLAIN
  • Raw database format as plain text with no XHTML or WIKI markup. Can be converted to VIEW representation by converting newlines to <br> and representing URLs as HTML links.
• RAW
  • Raw "database" format.
• STORAGE
  • Raw database format, for content that stores data in our XML storage format
• STYLED_VIEW
  • A rendered view that includes inline styles in a element, wrapped in an entire structure.