Create Issue Meta Endpoint Deprecation

Jira Development Jira Cloud
, , , ,
1

Hi Developer Community, we just deprecated the Create Issue Meta Endpoint. Please have a look at the Create Issue meta Endpoint Deprecation Notice for more details.

1 Like
2

@TrevorLao I looked at the REST API docs for this change and noticed that the schema does not look correct.

  • The issueTypes property in the issue type metadata endpoint response schema lists the fields property. I thought this was meant to be removed with this deprecation notice.
  • The field metadata endpoint response schema lists both fields and results properties with the same type definition. I assume only one of them is correct.
  • The definitions of the fields array items (FieldCreateMetaBeans) in field metadata endpoint response schema lists both fieldId (seems to be new) and key. Whatā€™s the difference between those? Which one should be used?

There may be other fields wrongly declared in the API spec. I did not check all the fields against the actual API response but these seem wrong.

3

@TrevorLao, one more question came up:

Will the following two endpoints coexist going forward?

Based on the docs, they are doing almost the same thing. We rely on the former because it supports the level parameter, but it is not paginated, unlike the metadata endpoint.

4

Hey @TrevorLao, could you help me understand the idea behind the intended use of the field metadata endpoint and why it needs to be paginated.

From the developerā€™s point of view, this is pretty awkward to use. Typically, you would fetch this endpoint to get a list of fields a user has to fill in to create an issue. Some of those fields may be required.

As I understand, the fields are returned in no particular order, i.e. there could be a required field on the last page of the API responses. As a result, as a developer, I would have to call that API endpoint repeatedly until I fetched all the pages, and only at that point can I start rendering the issue form.

Is this really how it was intended to work? It seems to defeat the point of making the endpoint paginated.

5

@TrevorLao, one more question came up:

Will the following two endpoints coexist going forward?

Based on the docs, they are doing almost the same thing. We rely on the former because it supports the level parameter, but it is not paginated, unlike the metadata endpoint

Apologies for the late reply.
Yes, we are not planning on making changes to get issue types for project endpoint as part of this deprecation.

6

Is this really how it was intended to work?

This should not affect the majority of issues as they should not need to paginate. For those that do, this change was created to alleviate the problems that were occurring as a result.

As I understand, the fields are returned in no particular order,

The fields should come in order of fieldId.

I would have to call that API endpoint repeatedly until I fetched all the pages, and only at that point can I start rendering the issue form.

I understand that this adds complexity to callers but supporting unbound lookup is not scaleable for our largest customers, but by introducing limits and pagination, we can ensure that this endpoint reliably works for all customers.

7
  • The issueTypes property in the issue type metadata endpoint response schema lists the fields property. I thought this was meant to be removed with this deprecation notice.

Iā€™m not seeing this value anymore. Maybe it was fixed?

  • The field metadata endpoint response schema lists both fields and results properties with the same type definition. I assume only one of them is correct.

results is just a standard that all our existing paginated objects follow. In this case, they point to the same value. This could help in migrating to the new endpoint as fields was used in the old endpoint.

  • The definitions of the fields array items (FieldCreateMetaBeans) in field metadata endpoint response schema lists both fieldId (seems to be new) and key. Whatā€™s the difference between those? Which one should be used?

fieldId is a new field, but it takes its value from key. There are no substantial differences and either can be used.

8

I may be a bit late, but Iā€™m currently working to change our code to migrate this deprecation and I struggle a bit with the following:
We currently use this endpoint to filter the available fields used in a new gen project to show the customer only the fields that are used in the project. For most of the fields thatā€™s quite easy as we just can use the ā€˜scopeā€™ information, but there is one exception:

  • Global Custom Fields used in Next Gen Projects
    Using the new APIā€™s we would need to call the API for every issuetype available in the next gen project

/rest/api/3/issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId}

I tried to find an alternative API, but was not yet able to find something. Does someone know an API that return the fields that can be used in a next gen project? (including global custom fields that are actually used there)

9

Using the new APIā€™s we would need to call the API for every issuetype available in the next gen project

I understand that it might not be ideal but this was our intended outcome of breaking down the existing create meta endpoint.

10

Hi @TrevorLao,

We missed this deprecation notice and are currently working to change our code, but we are afraid that this will impact our customers if the endpoint is removed in the next days.
Is there a new date for when this endpoint will be removed?
Also what is the best way to get notifications on such deprecation notices for Jira Cloud?

1 Like
11

@jhuertas,

Weā€™re working really hard to make the changelog the source of truth about deprecations (and other API changes). Using it for notifications depends on RSS. Many developers wire up the RSS feed to Slack to help make the notifications more ā€œactiveā€.

First, tune your filters, like to focus on deprecations (types) and/or Jira Platform (components), then ā€œGenerate feedā€:

image
image1728Ɨ816 109 KB

1 Like
12

@ibuchanan thank you for the follow up to @jhuertas.
Do you know when this deprecation goes into effect, i.e. when the deprecated API will stop working? We are trying to figure out how much time our customers have to upgrade.

-Sanjiva

13

@snath,

See CHANGE-1304:

The Get create issue metadata endpoint will be deprecated 6 months from now, on Jun 3, 2024. After which, the endpoint will return a 404 - Not Found error.

So it should have been removed 2 months ago (sorry, our teams sometimes say ā€œdeprecatedā€ when they mean ā€œremovedā€). I donā€™t have a new date. Iā€™d consider this to be on ā€œborrowed timeā€.

@TrevorLao, do you have any updates?

14

Hi @ibuchanan
We were initially intending on deprecating the endpoint 2 months ago but after reviewing the usage, we are still seeing a lot traffic for this endpoint. We are in the process of pushing out a deprecation strategy that should minimise the amount of friction involved in turning off this endpoint. Ideally, we would like consumers to treat it as a deprecated endpoint and migrate off it as soon as possible.

1 Like
15

@ibuchanan if the existing createmeta is being removed then this will affect us as well.

We need to get all available fields and all of their allowable values, schema etc returned in the createmeta request with fields. That means all create screen fields in all projects. Currently the only way we can do that is to get a list of projects and then call get createmeta with up to 100 project ids as a time.

So if the customer has 1000 projects (we have customers with higher than that) then we would need to do 10 calls. With the new setup, assuming there are on average 5 issue types per project, we would have to do 6000 REST API calls. As you can guess this isnā€™t going to work.

It would be good to just use the Field REST API but this doesnā€™t supply the same information as createmeta. Any suggestions on solving this?

Paul

16

@paul,

I trust your assessment that it is a problem but Iā€™m not sure I entirely understand why. Taken alone, I donā€™t see the problem with 6k API calls. Is there something that requires those requests to happen frequently? Or do you mean 6k requests before you can create an issue? I donā€™t follow why all that data would be needed. All that to say, no, I donā€™t have any technical solution.

My shallow understanding aside, we should get an issue ā€œon the booksā€ to express the gap. Could you please open a suggestion on JAC in the ECO project? It seems reasonable fill out the Field API with whatever is missing from createmeta. Once you have the issue key, please let us know here so other folks can watch, vote, and comment.

Otherwise, Iā€™m waiting to hear more about the deprecation strategy just like you.

17

@ibuchanan The calls need to be done when our apps page is loaded, from the front end. So whenever someone visits the page those calls need to be done before displaying anything. I need to make sure I have a list of all available fields and their allowed values, schema etc.

I opened a ticket under ECO but there wasnā€™t really any matching component so I just choose Connect-Frameworks. https://jira.atlassian.com/browse/ECO-384

Regards, Paul

1 Like
18

@paul,

Thanks for the issue. Weā€™ve done what we can for now. Hopefully, we can get ECO-384 done and you can get over to the Fields endpoint.

For longer term, I want to warn that we might stay ā€œin limboā€ for a long time. What might happen is that we neither build the Fields endpoint, nor finish the removal of createmeta. I would warn that doesnā€™t change the underlying performance problem with createmeta. Overtime, the very slow ratcheting towards the more atomic team-managed projects will shift the shape of configuration data. When CMP are the majority of projects, createmeta is efficient for clients because the fields are fewer than projects. When TMP are the majority, the ā€œ6k requests problemā€ become inevitable. As such, I urge some rearchitecture on your side, even if we donā€™t deliver. Perhaps your app could become more dynamic and get users to help refine project before needing all the fields? I donā€™t know your appā€™s features/functionality, so I couldnā€™t work through architecture here. However, I also want to be clear that shifting towards ā€œper projectā€ configuration is somewhat necessary.

Please keep raising the flag when you have problems. We do need to give you the time & information to make the change.

19

@ibuchanan

When this deprecated change first came out we planned just to stick with the old version so if nothing happens we will continue as before.

We have looked at trying to re-architect this several times before, since it is really slow for big customers, but have always failed. We have also contacted Atlassian staff through our TPM (when we had one) but they also couldnā€™t suggest a way around it. We will take another look at this again and see if we can think of ways to work around the problem.

Thanks for your help, Paul