API version 2

The Freshmaker API version 2 is mostly same as the API version 1. This document therefore describes only the differences between these two API versions.

Event JSON representation

The Freshmaker Event is always represented in the API request as JSON, for example:

{
    "builds_summary": {
        "total": 0
    },
    "depending_events": [],
    "depends_on_events": [],
    "dry_run": false,
    "event_type_id": 10,
    "id": 18730,
    "message_id": "message_123",
    "requested_rebuilds": [],
    "requester": null,
    "requester_metadata": {},
    "search_key": "44637",
    "state": 3,
    "state_name": "COMPLETE",
    "state_reason": "4 images rebuilt.",
    "time_created": "2019-08-01T07:00:46Z",
    "time_done": "2019-08-01T07:03:12Z",
    "url": "/api/1/events/18730"
}

The meaning of almost all the fields is the same as in Event JSON representation using the API version 1.

There are following differences between API version 1 and API version 2:

  • The builds field is replaced with builds_summary.

builds_summary - (JSON)

JSON object showing the summary of artifacts builds included in the Event grouped by their state_name. For example:

"builds_summary": {
    "total": 10,
    "DONE": 7,
    "FAILED": 3
}

Artifact Build JSON representation

The JSON representation of Artifact Build is exactly the same as in Artifact Build JSON representation using the API version 1.

REST API pagination

The pagination works exactly the same way as in REST API pagination using the API version 1.

HTTP REST API

GET /api/2/events/

Returns Freshmaker Events.

If id is set, only the Freshmaker Event defined by that ID is returned.

Query Parameters:

  • message_id (string) – Return only events with this message_id.

  • search_key (string) – Return only events with this search_key.

  • event_type_id (number) – Return only events with this event_type_id.

  • state (number/string) – Return only events int this state.

  • show_full_json (bool) –

    When True, the returned Freshmaker Event JSON objects contains all the fields described in the Freshmaker Event representation for API version 1.

    When False, the returned Freshmaker Event JSON objects are in the Freshmaker Event representation for API version 2 format.

    Default value for API version 1 is True, for API version 2 is False.

  • order_by (string) –

    Order the events by the given field. If - prefix is used, the order will be descending. The default value is -id. Available fields are:

Status Codes:
GET /api/2/events/(int: id)

Returns Freshmaker Events.

If id is set, only the Freshmaker Event defined by that ID is returned.

Query Parameters:

  • message_id (string) – Return only events with this message_id.

  • search_key (string) – Return only events with this search_key.

  • event_type_id (number) – Return only events with this event_type_id.

  • state (number/string) – Return only events int this state.

  • show_full_json (bool) –

    When True, the returned Freshmaker Event JSON objects contains all the fields described in the Freshmaker Event representation for API version 1.

    When False, the returned Freshmaker Event JSON objects are in the Freshmaker Event representation for API version 2 format.

    Default value for API version 1 is True, for API version 2 is False.

  • order_by (string) –

    Order the events by the given field. If - prefix is used, the order will be descending. The default value is -id. Available fields are:

Status Codes:
PATCH /api/2/events/(int: id)

Manage Freshmaker event defined by ID. The request must be application/json.

Returns the cancelled Freshmaker event as JSON.

Sample request:

PATCH /api/1/events HTTP/1.1
Accept: application/json
Content-Type: application/json

{
    "action": "cancel"
}
JSON Parameters:

  • action (string) – Action to do with an Event. Currently only “cancel” is supported.

Status Codes:
POST /api/2/builds/

Trigger manual Freshmaker rebuild. The request must be application/json.

Returns the newly created Freshmaker event as JSON.

Sample request:

POST /api/1/builds HTTP/1.1
Accept: application/json
Content-Type: application/json

{
    "errata_id": 12345,
    "container_images": ["foobar-1.2-234"]
}
JSON Parameters:

  • errata_id (string) – The ID of Errata advisory to rebuild artifacts for. If this is not set, freshmaker_event_id must be set.

  • container_images (list) – When set, defines list of NVRs of leaf container images which should be rebuild in the newly created Event.

  • dry_run (bool) – When True, the Event will be handled in the DRY_RUN mode.

  • freshmaker_event_id (bool) – When set, it defines the event which will be used as the dependant event. Successfull builds from this event will be reused in the newly created event instead of building all the artifacts from scratch. If errata_id is not provided, it will be inherited from this Freshmaker event.

Status Codes:
GET /api/2/verify-image/(image)

Verifies whether the container image defined by the NVR is handled by Freshmaker. If not, returns explanation why.

Sample request:

GET /api/1/verify-image/foo-1-1 HTTP/1.1
Accept: application/json

Sample response:

{
    "images": {
        "foo-1-1": [
            "content-set-1",
            "content-set-2"
        ]
    },
    "msg": "Found 1 images which are handled by Freshmaker."
}
Status Codes:

  • 200 OK – Image is handled by Freshmaker.

  • 400 Bad Request – Image is not handled by Freshmaker or not found.

GET /api/2/verify-image-repository/(project)/(repo)

Verifies whether the container image repository is handled by Freshmaker. If not, returns explanation why.

Sample request:

GET /api/1/verify-image-repository/foo/bar HTTP/1.1
Accept: application/json

Sample response:

{
    "repository: {
        "auto_rebuild_tags": [
            "latest"
        ],
    },
    "images": {
        "foo-1-1": {
            "content_sets": [
                "content-set-1",
                "content-set-2"
            ],
            "tags": [
                "latest",
                "2.0"
            ]
        }
    },
    "msg": "Found 1 images which are handled by Freshmaker."
}
Status Codes:

  • 200 OK – Image repository is handled by Freshmaker.

  • 400 Bad Request – Image repository is not handled by Freshmaker or not found.

POST /api/2/async-builds/

Trigger Freshmaker async rebuild (a.k.a non-CVE rebuild). The request must be application/json.

Returns the newly created Freshmaker event as JSON.

Sample request:

POST /api/1/async-builds HTTP/1.1
Accept: application/json
Content-Type: application/json

{
    "dist_git_branch": "main",
    "container_images": ["foo-1-1"]
}
JSON Parameters:

  • dist_git_branch (string) – The name of the branch in dist-git to build the container images from. This is a mandatory field.

  • container_images (list) – A list of images to rebuild. They might be sharing a parent-child relationship which are then rebuilt by Freshmaker in the right order. For example, if images A is parent image of B, which is parent image of C, and container_images is [A, B, C], Freshmaker will make sure to rebuild all three images, in the correct order. It is however possible also to rebuild images completely unrelated to each other. This is a mandatory field.

  • dry_run (bool) – When True, the Event will be handled in the DRY_RUN mode.

  • freshmaker_event_id (bool) – When set, it defines the event which will be used as the dependant event. Successfull builds from this event will be reused in the newly created event instead of building all the artifacts from scratch. The event should refer to an async rebuild event.

  • brew_target (string) – The name of the Brew target. While requesting an async rebuild, it should be the same for all the images in the list of container_images. This parameter is optional, with default value will be pulled from the previous buildContainer task.

Status Codes: