Jira v2 REST API项目版本查询query参数未按预期生效

根据Atlassian官方Jira Cloud v2 REST API文档说明，项目版本查询接口支持query请求参数。

该参数官方说明为：使用传入的字符串字面量过滤结果，返回name或description字段匹配的版本（匹配规则为不区分大小写）。

实际调用时该参数并未按照文档描述的逻辑正常工作。
调用接口地址https://my-jira-host/rest/api/2/project/project-key/version?query=july&orderBy=name时，返回结果包含大量与关键词“july”完全无关的版本数据。
接口返回响应示例如下：

{
  "self": "https://my-jira-host/rest/api/2/project/project-key/version?maxResults=50&orderBy=name&startAt=0",
  "nextPage": "https://my-jira-host/rest/api/2/project/project-key/version?maxResults=50&orderBy=name&startAt=50",
  "maxResults": 50,
  "startAt": 0,
  "total": 56,
  "isLast": false,
  "values": [
    {
      "self": "https://my-jira-host/rest/api/2/version/10302",
      "id": "10302",
      "name": "2017.07 Phoenix",
      "archived": false,
      "released": true,
      "startDate": "2017-07-03",
      "releaseDate": "2017-07-31",
      "userStartDate": "03/Jul/17",
      "userReleaseDate": "31/Jul/17",
      "projectId": 10607
    },
    {
      "self": "https://my-jira-host/rest/api/2/version/10303",
      "id": "10303",
      "name": "2017.08 Zelos",
      "archived": false,
      "released": true,
      "startDate": "2017-08-01",
      "releaseDate": "2017-08-31",
      "userStartDate": "01/Aug/17",
      "userReleaseDate": "31/Aug/17",
      "projectId": 10607
    },
    {
      "self": "https://my-jira-host/rest/api/2/version/10304",
      "id": "10304",
      "name": "2017.09 Horen",
      "archived": false,
      "released": true,
      "startDate": "2017-09-01",
      "releaseDate": "2017-09-30",
      "userStartDate": "01/Sep/17",
      "userReleaseDate": "30/Sep/17",
      "projectId": 10607
    }
  ]
}

问题原因 #

从返回结果的self字段可以看到，接口返回的分页链接里完全没有携带query=july参数，说明该参数没有被接口识别处理，常见诱因有两个：

• 你使用的Jira实例版本过低，query参数是后续版本迭代新增的能力，旧版本接口会直接忽略未识别的请求参数，返回全量分页的版本数据
• 部分Jira Cloud实例存在已知缺陷：当请求同时携带orderBy参数时，query参数的过滤逻辑会被直接跳过。

临时解决方法 #

• 先尝试移除orderBy参数，单独传递query参数调用接口，验证过滤逻辑是否生效
• 如果调整参数后过滤依然不生效，直接在客户端侧对接口返回的全量版本数据做二次过滤，判断版本的name、description字段是否包含查询关键词即可，实现成本很低。

内容的提问来源于stack exchange，提问作者Marcel Stör