Navigating Jira API Inconsistencies: Six Ways to Pass Issue Status Parameters

Previously I wrote two articles titled "Jira API Pitfalls" and "Ranting About API Docs" that documented many of the challenges when integrating Jira's API. I assumed most of the traps had been uncovered, but a recent functional change revealed new chaos in the Jira API.

The motivation behind this post is the need to wrap additional Jira API functionalities to achieve finer‑grained defect management, statistics, and notifications. After reviewing several API documents, I quickly ran into frustrating inconsistencies.

Although we are using a newer Jira version, the older documentation still largely works, indicating good backward compatibility. However, the API does not provide a smooth path for new features, and the parameter handling for issue status fields is especially problematic.

When dealing with the issue status field, Jira offers six different ways to pass parameters, each using different fields that are not mutually compatible. The most confusing part is the inconsistency of the name value across interfaces—for example, the closed status appears as Closed in the search API but as 关闭 in the statistics API.

Typically, a status is represented by a human‑readable name for front‑end display, while the back‑end stores an integer id. To keep the API design consistent, the id is used for data transmission, and the front‑end converts the id back to name for display.

Below are the six Java helper methods that illustrate the different parameter‑passing patterns I encountered:

public static JSONObject getId(int id) {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("id", id + "");
    return jsonObject;
}

public static JSONObject set(String str) {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("set", str);
    return jsonObject;
}

public static JSONObject getId(String id) {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("id", id);
    return jsonObject;
}

public static JSONObject getValue(int id) {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("value", id);
    return jsonObject;
}

public static JSONObject getName(String name) {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("name", name);
    return jsonObject;
}

public static JSONObject getIdValue(int id, String value) {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("id", id + "");
    jsonObject.put("value", value);
    return jsonObject;
}

These snippets demonstrate the various ways the API expects data, highlighting why careful handling of name and id is essential to avoid mismatches.

Have Fun ~ Tester!