Insights and Pitfalls When Working with the Jira REST API

I originally intended to write a rant about Jira's API, but ended up learning a lot of new standards and best practices while working with it, so this piece combines both the API's shortcomings and its well‑designed aspects.

No Chinese Documentation

Jira's API documentation is only available in English, which makes it difficult for developers with limited English proficiency to read and translate, especially when browser translation tools also translate URL paths.

HTTP Status Codes

Jira uses standard HTTP status codes to indicate business processing results rather than custom business codes, requiring developers to handle each code explicitly, especially 201 (Created) and 204 (No Content) for POST and PUT operations.

201 Created

The request succeeded and a new resource was created, with its URI returned in the Location header; otherwise, 202 Accepted is used.

204 No Content

The server successfully processed the request but returns no body, only possibly updated metadata in headers.

Inconsistent Responses

Jira's responses are all JSON, but the outer structure varies widely across endpoints, forcing developers to write custom parsers for each case.

{
    "issues": [
        {"id": "10000", "key": "TST-24", "self": "http://www.example.com/jira/rest/api/2/issue/10000"},
        {"id": "10001", "key": "TST-25", "self": "http://www.example.com/jira/rest/api/2/issue/10001"}
    ],
    "errors": []
}

{"id": "10000", "key": "TST-24", "self": "http://www.example.com/jira/rest/api/2/issue/10000"}

More complex nested structures can contain multiple layers of objects and arrays, making it hard to locate the needed fields.

Over‑Packaging

Typical API parameters are simple key‑value pairs, but Jira often wraps them in three layers of JSON, as shown in the following examples.

{
    "update": {
        "worklog": [{"add": {"timeSpent": "60m", "started": "2011-07-05T11:05:00.000+0000"}}]
    },
    "fields": {
        "project": {"id": "10000"},
        "summary": "something's wrong",
        "issuetype": {"id": "10000"},
        "assignee": {"name": "homer"},
        "labels": ["bugfix", "blitz_test"],
        "timetracking": {"originalEstimate": "10", "remainingEstimate": "5"}
    }
}

{
    "startAt": 0,
    "maxResults": 1,
    "total": 1,
    "comments": [{
        "self": "http://www.example.com/jira/rest/api/2/issue/10010/comment/10000",
        "id": "10000",
        "author": {"self": "http://www.example.com/jira/rest/api/2/user?username=fred", "name": "fred", "displayName": "Fred F. User", "active": false},
        "body": "Lorem ipsum dolor sit amet...",
        "created": "2016-09-27T09:43:02.795+0000",
        "visibility": {"type": "role", "value": "Administrators"}
    }]
}

Demo Errors

Some examples in the documentation contain malformed JSON, such as incorrectly placed property descriptions inside the payload, which forces developers to manually correct the examples before using them.

Mixed Chinese/English Fields

Several field values in Jira issues appear in both Chinese and English, which can be confusing for international teams.

POST vs PUT

POST is used for creating resources, while PUT is for updating them.

POST is non‑idempotent; PUT is idempotent.

Both methods send JSON payloads in the same way, and in Java they share the same base class org.apache.http.client.methods.HttpEntityEnclosingRequestBase .

Have Fun ~ Tester！

FunTester testing framework architecture

Segmented random practice – simulating online traffic

Environment basics – FunTester tutorial

HTTP interface testing basics – FunTester tutorial

Rant about API documentation

Beginner's guide to automated testing

Choosing the right automation testing tool

Selenium 4 Alpha‑7 upgrade experience

Selenium 4 IDE features: low‑code trend and SIDE Runner

LT Browser – responsive web testing tool

Performance testing soft launch

Data‑driven automation testing

Android app testing knowledge base

Selenium 4 API changes