Hello Everyone, We are trying to integrate a non-Atlassian application with JIRA Software using their REST APIs and faced an issue when trying to write a client for the 'Search Issues' API. The JIRA REST APIs documentation - https://docs.atlassian.com/jira/REST/server/ provides a JSON schema for the for the api response but doesn't provide the following details - * What fields would be returned for an issue. * What are their types? * What are their properties? * Are any of them conditional? * What format would custom fields be returned? So based on our feedback a new feature request has been created for this but as you all must be aware, it needs to be a popular demand to be picked up and looked at for implementation. So if you are facing similar issues and/or need the above information kindly go to this link JRASERVER-65654 and vote. Thank you for your support. Thanks & Regards, Vijay

nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

REST API Response Documentation - New Feature Request JRASERVER-65654

Vijay Anand

Hello Everyone,

We are trying to integrate a non-Atlassian application with JIRA Software using their REST APIs and faced an issue when trying to write a client for the 'Search Issues' API.

The JIRA REST APIs documentation - https://docs.atlassian.com/jira/REST/server/ provides a JSON schema for the for the api response but doesn't provide the following details -

What fields would be returned for an issue.
What are their types?
What are their properties?
Are any of them conditional?
What format would custom fields be returned?

So based on our feedback a new feature request has been created for this but as you all must be aware, it needs to be a popular demand to be picked up and looked at for implementation.

So if you are facing similar issues and/or need the above information kindly go to this link JRASERVER-65654 and vote.

Thank you for your support.

Thanks & Regards,

Vijay

Accepted answers

All comments

Nic Brough -Adaptavist-

It already does most of this:

1. What fields would be returned for an issue.

Whatever fields exist and have data for the issue. It's a variable list, and the response contains all the fields available. See rest/api/2/issue

2. What are their types?

See rest/api/2/field (I'd like to see the option to get data on a single field)

3. What are their properties?

Issue properties are retuenred the same as in 1, if they have been set, but you do need to ask for tem

4. Are any of them conditional?

This one is only partially possible, and has not been implemented yet, as far as I can tell. You would of course need to ask within the context of an issue, as field configurations can vary by project and issue type. The other way to make fields mandatory is to use validators, and I doubt that will ever be implemented, as it would require JIRA to be able to read the code in a plugin providing a validator to work out exactly what it was doing.

5. What format would custom fields be returned?

See rest/api/2/issue

Vijay Anand

Hello Nic,

Thank you for your response.

rest/api/2/field says that the type of 'issuetype' is 'issuetype'. Similarly for 'priority', 'resolution' etc.

Where does it say what properties does this 'issuetype' type contain? I could of course create an issue, check the api response and figure this out but there's another field called 'aggregateprogress' which is of type 'progress' and this has conditional properties. I discovered this by accident!

Also the field 'project' has a conditional property called 'projectCategory'. Now if I don't create project categories and just check the response I wouldn't know about this. So i'll end up writing a client that ultimately either ignores projectCategory or worse throws some error.

And who's to say that 'issuetype' doesn't have conditional properties? Where is it specified in the documentation that 'issuetype' has only 3 / 4 / 5 properties and they are so and so..

We are trying to import a lot of data from JIRA and it is vital that the information is correct. So we really do need this feature. There's no way in the current set up to get this information and so we can only hope that we've got most of it right.

Nic Brough -Adaptavist-

Yes, that's correct. The issuetype field is an issuetype, priority is a priority and so-on. They are built in fields with specific defined properties you should be reading from the API docs.

If your code doesn't process projectCategory - so what? It's your choice not to look at it. Not knowing it is there is not going to cuase you any problems. You would only work with it if you want your code to do something with the project categories, but that should be in your requirements, not guessed at because of an overloaded response.

Properties are not "conditional", they all exist for the objects they belong to. They may be empty. They vary appropriately for each type of object they belong to. That's up to the data the users have placed on the issues, and/or the configuration in JIRA.

>We are trying to import a lot of data from JIRA and it is vital that the information is correct.

It is correct. What you're asking for is JIRA to explain it all to you in great detail. But that's of no use for most REST applications and even if you did get it, you are still going to need to understand JIRA in order to use it.

The short answer here is that you need to decide what you actually want from the data you are asking JIRA for and then code appropriately. Not expect JIRA to tell you everything and then blindly attempt to code for it without knowing what it is for.

Vijay Anand

>They are built in fields with specific defined properties you should be reading from the API docs.

Which doc are you referring to that mentions what the defined properties are?

> If your code doesn't process projectCategory - so what? It's your choice not to look at it. Not knowing it is there is not going to cuase you any problems. You would only work with it if you want your code to do something with the project categories, but that should be in your requirements, not guessed at because of an overloaded response.

The requirement gathering is dependent on what we know about the API response. Only if we know that project category is returned in the api response can we make a decision on how to handle it. If we don't know this information might be missed.

>Properties are not "conditional", they all exist for the objects they belong to. They may be empty. They vary appropriately for each type of object they belong to. That's up to the data the users have placed on the issues, and/or the configuration in JIRA.

In fact they are not empty. For the "Progress" type the property "percent" doesn't appear in every response. My point here again is that to understand the api response we cannot be creating every sort of issue and then taking a look at the response to figure out what new fields and properties have appeared. We should be able to just rely on the documentation.

>It is correct. What you're asking for is JIRA to explain it all to you in great detail. But that's of no use for most REST applications and even if you did get it, you are still going to need to understand JIRA in order to use it.

I disagree. I think it's absolutely vital to any REST application that thinks that other applications might need integrate with it in any way, import/export.

>The short answer here is that you need to decide what you actually want from the data you are asking JIRA for and then code appropriately. Not expect JIRA to tell you everything and then blindly attempt to code for it without knowing what it is for.

The requirement is we want issue data. JIRA needs to tell us what all fields are there inside an issue. It is not our job to try out every permutaion and combination of issue to figure out the different fields.

Nic Brough -Adaptavist-

It's hard to start to tell you how you are getting this wrong.

Basically, your requirement is broken. "We want issue data" is not a requirement, it's a statement about part of a process.

All of your points (barring the first one about documentation) are obviated by the fact that you don't understand what you're getting or how to handle it.

The REST calls respond with the issue data, so your stated requirement really is already met. Your problem is that you don't understand that data, and you're expecting JIRA to explain it. Even if it tried to do that, it's pretty much useless without the context of what you actually want to do with it.

Let me give you a really simple example:

Answer: 42

JIRA could explain it further in the REST response, but it wouldn't help you in the slightest.

You need to define what you actually want to do with that answer and what it means to you.

Vijay Anand

Nic, our requirement is not broken, you have just assumed that requirements have to be a specific way.

When I say that we need issue data it means that we want every single field, every single property, every small piece of information that can be stored about an issue, doesn't matter what kind of issue it is. We will decide how to handle the information once we know what is available.

As to why we need it this way I can't tell you without revealing the internals of our application.

So please don't assume that something is wrong or broken because you don't understand it.

Nic Brough -Adaptavist-

I had to assume it is broken because what you gave me is broken. It's not a useful requirement.

At least the clarification that you simply want to grab everything from an issue is clear enough to work with.

And that's easy to answer. JIRA is already giving you the data it has for an issue in the response.

Your application is going to need to be written to expect those variations in the data. There's no point in asking JIRA "what shape is the data I am going to get for an issue" when the response could (and probably will be) different for each issue. It's no good saying "every single field, every single property, every small piece of information that can be stored about an issue" - one issue might have only 5 data points, the next one 250. It's down to how that particular JIRA is configured, and you have to understand that to be able to interpret what you're getting. JIRA can't explain it to you without effectively giving you a complete specification on how JIRA works along with all the data. That's never going to happen.

There's no way to know what you might get from a "give me everything" You have know what you want to do with the data in order to ask the right question. If you're asking for everything, you need to do the work to understand it, the computer has answered the question of "everything", it's up to you to make meaning of it.

Vijay Anand

I thought it was fairly obvious from all the points I was making in my previous comments. If you didn't understand you could've asked for a clarification instead of just saying my requirement is broken.

Anyway, you still don't seem to understand what I require. I don't want the response to return every single field. I want this information in the documentation. The response should return only what is relevant for that specific issue but the documentation should mention all the different fields and properties and what not. So then my application is prepared to handle all the different variations.

And I guess there are a few folks in JIRA who think that my requirement is reasonable enough, and not broken, to create a new feature request.

Nic Brough -Adaptavist-

That's not what you said before, and no, it's not obvious from your points - if it were, I'd have been agreeing with them.

I do understand what you think you require, and that's not going to happen. Your real requirements have not been shared, which is fine, but you miss the point that if you don't understand the question you're asking, you're not going to get a useful answer.

I guess we'll just have to disagree on some of these points.

I agree that the REST documentation could be improved, but it's never going to document what you think you need.

Simple example - if your JIRA has one of my old plugins installed, there's a field which will appear in "all data for an issue" that will never be documented by Atlassian. You would need to understand why it's there and what it does before you'll be able to use it.

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

jira

jira-software

rest-api