Deprecation Notice: deprecation of custom field options APIs (+new APIs published)

Jira Development Jira Cloud Announcements
, , , ,
#1

Hi Everyone,

We’re excited to announce that we’ve recently published new Jira APIs for custom field options management.
These brand new APIs support custom field options in both global and project-specific contexts.
It’s a full set of APIs to read, create, update, delete and reorder custom field options:

Starting from 7th of May 2021 the following, legacy APIs for custom field options will be no longer available, i.e.:

The legacy APIs have some issues (no project-specific context support, no delete, etc.) that are fully addressed in new release.
So, if you’re using the legacy APIs - please change your code to utilise the new ones.
If you have any questions, let us know in the comments.

Thanks!

9 Likes
GET /rest/api/3/customField/{fieldId}/option fails for non-global custom fields
REST API can't get custom field options
JIRA REST API can't get custom field options
Change in permissions for GET custom field option API
#2

Hi @TomaszZasada,

thank you for the great API endpoints. They are really much appreciated.

While developing against those endpoints I found an issue with the Update custom field options (context) endpoint. Changing the value of options in bulk works well as expected. But changing the disabled boolean in bulk will result in the following error. This only affects changing multiple options at once where the value stays the same and only the disabled bool changes.

{
    "errorMessages": [
        "An option value must be unique in its field and a cascading option value must be unique in its option."
    ],
    "errors": {}
}

I also noticed that the endpoints are not working with next-gen custom fields. I guess this is intended behaviour? Just wanted to double check.

Thanks,
Thomas

#3

Hi @TomaszZasada
Is there any plan for changing Issue Field Options API’s also?

#4

Hi @ChakreshTiwari,
There are no plans to change Issue Field Options API. What changes do you mean exactly?
Is there anything missing in those APIs?

#5

Hi @thomas1,
Can you please paste exact request (path, body) that you send?

#6

Thanks for the response @TomaszZasada
I am talking about reorder and enable/disable Api’s For Issue Field Options.

#7

@TomaszZasada
of course. The following path & body combination results in the error I posted above:

/rest/api/2/field/customfield_10113/context/10219/option

{
   "options":[
      {
         "id":"87610",
         "disabled":true
      },
      {
         "id":"87611",
         "disabled":true
      }
   ]
}
STATUS:400 Bad Request

using the same path with just on option works though.

{
   "options":[
      {
         "id":"87610",
         "disabled":true
      }
   ]
}

STATUS:200 OK

I also tried sending the value of an option, but that didn’t change the outcome. To reproduce this you must flip the disabled value to what it was previously (actually change it) or it will run through as well.
Let me know if you need more information to reproduce this.
Thanks

#8

Thanks @thomas1,
It really looks like a bug. Thanks for putting this up!
We’re going to fix it as soon as possible.
I will let you know when it’s done.
PS. Yes - the APIs work only with classic projects. Currently, there are no plans to accommodate for next-gen projects.

2 Likes
#9

No, unfortunately no plans to implement it in the nearest future.

#10

Hi,
thank you for reporting the issue, @thomas1.
I’d like to let you know that it was fixed and deployed on production.

1 Like
#11

Hi @BeataSzturemska
thank you for the quick fix. I can confirm that it works on my end as well. :+1:

1 Like
#12

Hello,

I have some difficulties to retrieve options from a Next gen dropdown fields.

I create 2 fields:

  • a dropdown (select) customfield (customfield_10136)
  • a next gen dropdown fields (customfield_10135)

https://xxxxxxxxxxxxxxxxxx.atlassian.net/rest/api/3/field

{
        "id": "customfield_10135",
        "key": "customfield_10135",
        "name": "[nextgen] Dropdown",
        "untranslatedName": "[nextgen] Dropdown",
        "custom": true,
        "orderable": true,
        "navigable": true,
        "searchable": true,
        "clauseNames": [
            "[nextgen] Dropdown",
            "[nextgen] Dropdown[Dropdown]",
            "cf[10135]"
        ],
        "scope": {
            "type": "PROJECT",
            "project": {
                "id": "10009"
            }
        },
        "schema": {
            "type": "option",
            "custom": "com.atlassian.jira.plugin.system.customfieldtypes:select",
            "customId": 10135
        }
    },
 {
        "id": "customfield_10136",
        "key": "customfield_10136",
        "name": "Dropdown CF",
        "untranslatedName": "Dropdown CF",
        "custom": true,
        "orderable": true,
        "navigable": true,
        "searchable": true,
        "clauseNames": [
            "cf[10136]",
            "Dropdown CF",
            "Dropdown CF[Dropdown]"
        ],
        "schema": {
            "type": "option",
            "custom": "com.atlassian.jira.plugin.system.customfieldtypes:select",
            "customId": 10136
        }
    },

Now I want to retrieve the context of my fields in order to call the new “retrieve options” endpoint:
With a customfield the new end point works fine:

https://xxxxxxxxxxxx.atlassian.net/rest/api/3/field/customfield_10136/context

{
    "maxResults": 50,
    "startAt": 0,
    "total": 1,
    "isLast": true,
    "values": [
        {
            "id": "10244",
            "name": "Default Configuration Scheme for Dropdown CF",
            "description": "Default configuration scheme generated by Jira",
            "isGlobalContext": true,
            "isAnyIssueType": true
        }
    ]
}

But with my next gen dropdown fields I get the following error:
https://xxxxxxxxxxx.atlassian.net/rest/api/3/field/customfield_10135/context

{
    "errorMessages": [
        "The custom field was not found."
    ],
    "errors": {}
}

No context given: I can’t use the endpoint to retrieve my options:
https://xxxxxxxxxxxxxxx.atlassian.net/rest/api/3/field/customfield_10135/context/???/option

am I using the correct method to retrieve option of a next gen dropdown fields ?

Thank you in advance !
Kind regards,
Basile Grandperret

3 Likes
#13

Hi @BeataSzturemska, @TomaszZasada ,

we have a few questions regarding the new API and the upcoming deprecation on May, 8.

  1. Is there any way to flag our instances so that we can test against the upcoming changes beforehand?
  2. As far as I can see, the /search API currently returns the deprecated URL in the self link:
         "customfield_10129": {
            "1": {
              "self": "https://vleletko.atlassian.net/rest/api/3/customFieldOption/10128",
              "value": "other 2 ",
              "id": "10128"
            }
          }

Will the new URL be returned there on May 8, when the old API is removed? Can we count on it?
3. After the change, will custom field option IDs still be globally unique, i.e. not just unique in the scope of context? This is crucial for our internal storage - we need to store information about the selected custom field option, and this influences the ID that we store.

Best regards
Igor Baltiyskiy
Structure Cloud developer in ALM Works

#14

Hi!
@BeataSzturemska @TomaszZasada is this jira issue macro bug also related to this api deprecation? Seems like it is.

#15

Hi @margus.nael,

I have confirmed that the issue you mentioned occurs on my prod instance. I suppose the problem is on the Confluence side so I have reached out to a proper team internally. I will keep you updated, but I believe it isn’t connected with the deprecation.

1 Like
#16

Hi @BeataSzturemska , @TomaszZasada ,

could you please follow up on the questions regarding the upcoming API removal?

  1. Can we test it in advance?
  2. What about /rest/api/3/search — will it return the new self URI on May, 8?
  3. Will custom field ID still be globally unique?

Thanks
Igor Baltiyskiy

#17

Hi @sank,

thank you for raising your concerns around the /rest/api/3/search endpoint.
What we are going to do is keeping GET /rest/api/3/customFieldOption/{id} without deprecation and still return it as self URI in the search endpoint.

GET /rest/api/3/customField/{fieldId}/option, create and update endpoints will be removed as we announced before however, we are not going to remove them immediately on 8th May. We should have the possibility to turn them off for particular instances soon and we’re going to switch them off for vendors who didn’t use them before.

This change has nothing in common with the uniqueness of custom field IDs, so identifiers will remain unchanged and unique as they were.

Regards,
Beata

1 Like
#18

It’s a kind of expected behaviour as it was announced here. In general, most Jira APIs don’t support next-gen entities.

#19

Thank you for your reply! I’m glad the GET /rest/api/3/customFieldOption/{id} remains, that solves it for us.

We should have the possibility to turn them off for particular instances soon and we’re going to switch them off for vendors who didn’t use them before.

May I request to include our instances into this? We most certainly don’t use the APIs, but it would be great to still test it before it hits the production.

1 Like
#20

Do we have any API to add more options to existing custom field of single select type??
Didn’t see that here

Also posted detailed question here