Is there documentation for api.atlassian.com/pf-editor-service/convert?

[Lars Norved]

I discovered the api https://api.atlassian.com/pf-editor-service/convert?from=markdown&to=adf 
for converting markdown to Atlassian Document Format used extensively in V3 of the jira api. 

I would like to know if the api can convert to other formats such as text and html.

[Dario B · Accepted solution]

Adding a summary of my replies in here and setting it as the accepted answer for this thread:

• I have created a Feature Request to have a public REST API endpoint to convert among formats:

  • JRACLOUD-77436 - - Provide a public REST API endpoint to convert between ADF, HTML, Markup and Markdown now that pf-editor-service has been decommissioned

• A slightly outdated version of the code is available in the public atlaskit repo:

  • https://bitbucket.org/atlassian/atlaskit-mk-2/src/master/packages/editor/editor-markdown-transformer/

You may want to vote and watch the above feature request so that you will get notified in case of any update. The  feature will be addressed according to the Implementation of New Features Policy.

Cheers,
Dario

[David Bakkers]

Bad news for everyone who comes looking for more information about the use of the pf-editor-service endpoint.... it's been decommissioned!

As of today, 18th Sep 2021, requests to that endpoint return a 404, Not Found error.

It would be really nice if someone, anyone, at Atlassian would advise what the endpoint was for, why it's now been decommissioned and what, if anything, it will be replaced with.

ADF really is an outlier page description language. Without broad industry support and a collection of libraries for various languages, it's never going to have the same 'plug-and-play' reliability of, say, XML or HTML.

[Dario B]

I have created a Feature Request to have a public REST API endpoint to convert among formats:

• JRACLOUD-77436 - Provide a public REST API endpoint to convert between ADF, HTML, Markup and Markdown now that pf-editor-service has been decommissioned

You may want to vote and watch the above feature request so that you will get notified in case of any update. The  feature will be addressed according to the Implementation of New Features Policy

Cheers,
Dario

[Dario B]

@Lars Norved @David Bakkers ,

You can find a slightly outdated version of the code available in the public atlaskit repo:

• https://bitbucket.org/atlassian/atlaskit-mk-2/src/master/packages/editor/editor-markdown-transformer/

Please give it a try and don't forget to vote and watch the Feature Request!

Have a nice weekend!

Dario

[David Bakkers]

Here is a table of the formats that the endpoint will convert from and to:

I found that:

1. 'markdown' means Jira markup encoded text.
2. 'wiki' means Confluence markup encoded text.
3. 'pm' means Page Markup, and essentially seems to be another name for ADF.

When supplying ADF content in the input of the request body, you have to use the full ADF format  like this:

{
  "input": {
    "version": 1,
    "type": "doc",
    "content": [
        {
            "type": "heading",
            "attrs": {
                "level": 1
            },
            "content": [
                {
                    "type": "text",
                    "text": "This is an H1."
                }
            ]
        },
        {
            "type": "paragraph",
            "content": [
                {
                    "type": "text",
                    "text": "This is "
                },
                {
                    "type": "text",
                    "text": "italic",
                    "marks": [
                        {
                            "type": "em"
                        }
                    ]
                },
                {
                    "type": "text",
                    "text": " and this is "
                },
                {
                    "type": "text",
                    "text": "bold",
                    "marks": [
                        {
                            "type": "strong"
                        }
                    ]
                },
                {
                    "type": "text",
                    "text": " in markdown"
                }
            ]
        }
    ]
  }
}

Enjoy :)

[David Bakkers]

Hello @Lars Norved 

How did you 'discover' that endpoint for that service? Where was it discussed or disclosed? I'm very keen to know more about it.

I've just been playing with sending POST requests to the endpoint and it definitely does convert markdown to ADF, as I sent a bunch of markdown and got ADF back. The method of supplying the content is via a field called 'input' in the body of the request:

{

     "input": "# This is an H1.\nThis is _italic_ and this is **bold** in markdown"

}

While experimenting with different from= values, I then got it to throw an error:

"error": "from should be equal to one of the allowed values: markdown, adf, html, text, wiki, pm"

So, looks like it can convert five different formats to ADF, or so it says.

However, when I tried:

https://api.atlassian.com/pf-editor-service/convert?from=html&to=adf

I got back:

"message": "Cannot convert from 'html' to 'adf'"

So, the endpoint is still in some sort of experimental / incomplete state, or only converts certain types to certain other types.

.... more experiments are in progress :)