Issue Occurrence

An IssueOccurrence links an Issue to the single KCIDB object (checkout, build, test or testresult) it was seen on. Exactly one of checkout_id, build_id, test_id or testresult_id must be set.

To attach one or more KCIDB objects to an Issue you already know, it’s usually more convenient to use the attach actions on the Issue endpoint instead of this one directly, e.g. POST /api/1/issue/$issue_id/tests.

Get

Get a single IssueOccurrence.

GET /api/1/issueoccurrence/$issue_occurrence_id

Name	Type	Required	Description
`issue_occurrence_id`	`int`	Yes	ID of the IssueOccurrence.

Example of response:

{
    "issue": {
        "id": 1,
        "kind": {
            "id": 1,
            "description": "Kernel bug",
            "tag": "Kernel Bug"
        },
        "description": "Bug description.",
        "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
        "resolved": false,
        "resolved_at": null,
        "policy": {
            "id": 1,
            "name": "public"
        },
        "first_seen": "2022-03-16T08:55:51.749000Z",
        "last_seen": "2022-04-16T10:23:45.123000Z",
        "last_edited_at": "2022-04-16T10:23:45.123000Z",
        "upstream_status_description": null,
        "upstream_last_activity_at": null,
        "tags": [],
        "regexes": []
    },
    "is_regression": false,
    "created_at": "2022-04-14T05:33:09.415318Z",
    "checkout_id": null,
    "build_id": null,
    "test_id": "redhat:112448273",
    "testresult_id": null
}

List

Get a list of IssueOccurrences. Results use a lighter representation of the nested issue, without first_seen, last_seen, hit_count, last_edited_at or regexes.

GET /api/1/issueoccurrence

Example of response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "issue": {
                "id": 1,
                "kind": {
                    "id": 1,
                    "description": "Kernel bug",
                    "tag": "Kernel Bug"
                },
                "description": "Bug description.",
                "ticket_url": "https://bugzilla.redhat.com/show_bug.cgi?id=123456",
                "resolved": false,
                "resolved_at": null,
                "policy": {
                    "id": 1,
                    "name": "public"
                },
                "tags": []
            },
            "is_regression": false,
            "created_at": "2022-04-14T05:33:09.415318Z",
            "checkout_id": null,
            "build_id": null,
            "test_id": "redhat:112448273",
            "testresult_id": null
        }
    ]
}

Create

Create a new IssueOccurrence. (Auth Required: add_issueoccurrence permission)

POST /api/1/issueoccurrence

Request body should contain JSON with the issue occurrence data. Exactly one of checkout_id, build_id, test_id or testresult_id is required:

{
    "issue": 1,
    "test_id": "redhat:112448273"
}

Field	Type	Required	Description
`issue`	`int`	Yes	ID of the Issue.
`checkout_id`	`str`	Exactly one of these four	`id` of the KCIDB checkout.
`build_id`	`str`	Exactly one of these four	`id` of the KCIDB build.
`test_id`	`str`	Exactly one of these four	`id` of the KCIDB test.
`testresult_id`	`str`	Exactly one of these four	`id` of the KCIDB test result.
`is_regression`	`bool`	No	Whether this occurrence is a regression. Defaults to `false`.

Example of response: same format as Get.

Creating a duplicate occurrence (same issue and same KCIDB object) is idempotent: it returns 201 with the existing occurrence instead of an error, since the caller’s intent (that the link exists) is already satisfied.

Batch Create

To create several occurrences in one request, POST a JSON array instead of a single object:

[
    {"issue": 1, "checkout_id": "b8fba93561c984f336d47d6d544be3a2a920bac3"},
    {"issue": 1, "test_id": "redhat:112448273"}
]

The response is a JSON array of the created (or already-existing) occurrences, in the same format as Get. The whole batch is created atomically: if any item fails validation, none of the occurrences are created.

Partial Update

Update only some fields of a single IssueOccurrence. (Auth Required)

PATCH /api/1/issueoccurrence/$issue_occurrence_id

Name	Type	Required	Description
`issue_occurrence_id`	`int`	Yes	ID of the IssueOccurrence.

Updatable fields: is_regression.

Full Update

Completely replace a single IssueOccurrence. (Auth Required)

PUT /api/1/issueoccurrence/$issue_occurrence_id

Name	Type	Required	Description
`issue_occurrence_id`	`int`	Yes	ID of the IssueOccurrence.

Request body should contain the same fields as Create.

Example of response: same format as Get.

Delete

Delete a single IssueOccurrence. (Auth Required)

DELETE /api/1/issueoccurrence/$issue_occurrence_id

Name	Type	Required	Description
`issue_occurrence_id`	`int`	Yes	ID of the IssueOccurrence.

Responds with 204 and empty content.