REST API v2 no longer compatible with Jira, v3 still in beta

We just raised v3 being in beta as a bug on ECOHELP, since v2 no longer seems to be compatible with Jira. Let me explain:

With Deep Clone for Jira, we try to clone issues as close to the original issue as possible.

However, it looks like we’re not able to clone the description and make sure it stays identical when using v2 of the REST API. It seems to be possible with v3, but since v3 is still officially in beta, we’re not sure if we can use it. If there would be an incident with v3, we’d need to be sure that an incident would get the same severity as with the v2 API.

To reproduce:

  1. Create an issue with v3, this is probably what Jira uses internally (or at least an API supporting ADF):
POST /rest/api/3/issue

{
  "fields": {
    "project": {
      "key": "BEN"
    },
    "issuetype": {
      "name": "Task"
    },
    "summary": "Test for ADF",
    "description": {
      "version": 1,
      "type": "doc",
      "content": [
        {
          "type": "bulletList",
          "content": [
            {
              "type": "listItem",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Text text text."
                    },
                    {
                      "type": "hardBreak"
                    },
                    {
                      "type": "text",
                      "text": "- Text text text."
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}
  1. Fetch the issue with v2, this is what Deep Clone is doing:
GET /rest/api/2/issue/BEN-1390

Response:
...
  "description": "* Text text text.\n- Text text text."
...
  1. Clone the issue with v2 (replicating Deep Clone behavior):
POST /rest/api/2/issue

{
  "fields": {
    "project": {
      "key": "BEN"
    },
    "issuetype": {
      "name": "Task"
    },
    "summary": "Test for ADF",
    "description": "* Text text text.\n- Text text text."
  }
}
  1. Note the different appearance of the description in the screenshots attached. The bullet-point hierarchy present in BEN-1390 gets lost in BEN-1391, which is critical for certain customers to get this cloned correctly. Note that it might also affect other formatting options with ADF.

Screenshot 2022-12-15 at 10.54.55

Screenshot 2022-12-15 at 10.55.10

What we need is:

  • Either a workaround when using v2 so the description, comments, and any other fields using ADF can be cloned correctly
  • or, when using v3 of the REST API, we need a guarantee that it is ready for production use and the ability to raise incidents if we detect any issues with it.

v3 has apparently been in beta for more than 4 years now and it’s necessary for us to know if we can rely on it before using it extensively.

If any other app developers are interested in this, I’m happy to share any progress from the Bug we have raised that we’re allowed to share.

6 Likes

For everyone that wants to use the v3 REST API, I have received official confirmation from Atlassian that v3 can be used in production:

[…] we can confirm with the developer that despite the beta tag, production support is indeed guaranteed and we would treat an incident with this API with the same severity as the V2 API.

I have also asked Atlassian if I can share this with other developers, which they have agreed to. Hope they will remove the “beta” label soon so it’s less confusing going forward.

2 Likes