How can I determine the format of each field to send for an edit?

[dataservice]

I’m trying to write some generic code that can send edits for any field to Jira Cloud through the API. Simple fields like string and number seem pretty straightforward, but I’m having a hard time figuring out a generic way to send updates for complex fields (such as issuetype, project, user, or arbitrary custom fields). 

So far, it looks like the best way would be to use the editmeta (from GET /rest/api/2/issue/{issueIdOrKey}/editmeta) to dynamically determine the format, but that seems to be missing important information for several fields. Here are some examples of missing or unclear information from what I’ve seen with a Jira Cloud test instance and several Postman requests:

1. Editing the issuetype is successful with requests similar to the following: {"fields": {"issuetype": { "id": "10002" }}} on PUT /rest/api/2/issue/{issueIdOrKey}. The editmeta for this field does provide a list of allowedValues, although it doesn’t specify any operations. If no operations were specified, why did the edit succeed? 
2. Editing the Sprint (a custom field in our instance) succeeds with json such as {"fields": { "customfield_10020": 1 }} on PUT /rest/api/2/issue/{issueIdOrKey} where 1 is a sprint id. The editMeta for this field shows that “set” is an available operation and that the schema is { "type": "array", "items": "json", "custom": "com.pyxis.greenhopper.jira:gh-sprint", "customId": 10020 }. Why wasn’t the id required to be put in an id object like the id for issuetype? I don’t see any indication in the editMeta that that is what is required. Where could I find that indicated? What does an “array of json” mean for editing? Does the value of “custom” in the editMeta tell me anything useful for this?
3. Editing the epic link is by issue key string: {"fields": {"customfield_10014": "TEST1-63"}} on PUT /rest/api/2/issue/{issueIdOrKey}. The editMeta says that this is the schema: {"type": "any", "custom": "com.pyxis.greenhopper.jira:gh-epic-link",  "customId": 10014 }. I would expect that a type “any” would accept any value, so I tried 5 instead of “TEST1-63” and got an error saying "String value expected as the Epic Key.". Is there any way I could know beforehand what this would expect?
4. I haven’t been able to successfully add an issuelink. I’ve tried "update": { "issuelinks": [{"add": 10005}]} as well as the string key of an issue to link to and it didn’t work. It appears I also need an issuelink type. Is that something that will just have to be special cased in the update code?
5. I haven’t been able to find a field that does this again but yesterday I noticed that some fields that showed up in the editMeta would give me an error along the lines of “you can’t edit this on this page”. Why would the field show up in the editMeta if it’s not editable, or at least why wouldn’t it have some indication that it’s not editable?

I’ve seen a few other anomalies like this not listed here as well. I suppose my main questions then are

1. How can I tell from the editmeta for a field what the edit request should look like for that field?
2. Am I just missing something or going about this wrong?

[Warren · Accepted solution]

Hi @dataservice 

I write to lots of the fields (generic fields and customfields) in our projects, via the API, but I generally perform a GET and look at the format then mimic it. So to generalise it as you're wanting, I'm not sure. 

To answer a couple of your queries :

5. This usually appears when the field isn't on the Edit screen of that project - check and add the field

4. Below is some typical JSON to create an issue and link it to another. The name, inward and outward values are specific to your Jira instance

{
"fields": {
"project": {
"key": "DS"
},
"issuetype": {
"name": "Task"
},
"summary": "Linking issues",
"description": "Issue linking"
},
"update": {
"issuelinks": [
{
"add": {
"type": {
"name": "Relates",
"inward": "relates to",
"outward": "relates to"
},
"outwardIssue": {
"key": "DS-29"
}
}
}
]
}
}

[dataservice]

I've been waiting to see if any other answers came before accepting this as the answer. Thank you for your help on those couple of questions!