API version 1

Event JSON representation

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

{
    "builds": [],
    "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 fields used in the Freshmaker Event JSON have following meaning:

builds - (list of Freshmaker Artifact build JSONs): List of artifact builds which are part of this Freshmaker event.

depending_events - (list of numbers): List of IDs of other Freshmaker events which are depending on this Freshmaker event.

depends_on_events - (list of numbers): List of IDs of other Freshmaker events which this event depends on.

dry_run - (boolean): When set to true the event is handled in dry run mode. In this mode, no real builds are submitted to build system. Instead, all the builds are automatically moved to COMPLETE state.

event_type_id - (number)

The ID of the type of this Event. Full list of Event types can listed using the /api/1/event-types/ REST API. The most important event types are:

10 (ErrataAdvisoryStateChangedEvent) - Event triggered by message, rebuilding all artifacts (currently just container images) as result of advisory release.
13 (ManualRebuildWithAdvisoryEvent) - Event triggered manually, rebuilding all artifacts (currently just container images) as result of advisory release.

id - (number): The ID of Freshmaker event.

message_id - (string): The ID of message (fedmsg or AMQP) which triggered the Event.

requested_rebuilds - (list of strings): List of artifacts which should be rebuilt in this Freshmaker Event. Filled in only for manual rebuilds which requested particular artifacts to be rebuilt. Currently, it is always list of container images NVRs.

requester - (string or null): The Kerberos username of requester of this Freshmaker Event. Set to string only for manual rebuilds, otherwise null.

requester_metadata - (JSON object): Additional metadata set by requester when submitting the manual rebuild. It can be used to track the context of manual rebuild.

search_key - (string)

The key identifying source of the Event. For each Event type, there is a different way how the key is generated:

Event type 10 (ErrataAdvisoryStateChangedEvent) - The ID of advisory which triggered the Event.
Event type 13 (ManualRebuildWithAdvisoryEvent) - The ID of advisory which triggered the Event.

state - (number)

Number defining the state the Event is currently in:

0 (INITIALIZED) - Event is initialized and Freshmaker is now searching for artifacts to build.
1 (BUILDING) - Some artifacts to build have been found and Freshmaker is building them.
2 (COMPLETE) - All artifacts have been build. Note that this does not mean all the builds were successfull - just one successfull artifact build is enough to mark the Event as COMPLETE.
3 (FAILED) - There was some major error while handling the Event or all the artifact builds failed to build.
4 (SKIPPED) - No artifacts have been found to build or the Event is not allowed by the Freshmaker’s configuration.
5 (CANCELED) - Event has been manually cancelled using the REST API.

state_name - (string): Name of the state the Event is currently in. See state for more info.

state_reason - (string): Sentence describing the current state.

time_created - (datetime): The date and time on which the Event has been initialized (moved to INITIALIZED state).

time_done - (datetime): The date and time on which the Event has been moved to FAILED, COMPLETE, or CANCELED state.

Artifact Build JSON representation

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

{
    "build_args": {
        ...
    },
    "build_id": 22429387,
    "dep_on": "fedora-30-container",
    "dep_on_id": 21657,
    "event_id": 16730,
    "id": 21837,
    "name": "httpd-container",
    "odcs_composes": [],
    "original_nvr": "httpd-container-2.4-1",
    "rebuild_reason": "directly_affected",
    "rebuilt_nvr": "httpd-container-2.4-1.1561731291",
    "state": 1,
    "state_name": "DONE",
    "state_reason": "Built successfully.",
    "time_completed": "2019-06-29T03:28:56Z",
    "time_submitted": "2019-06-28T14:14:51Z",
    "type": 1,
    "type_name": "IMAGE",
    "url": "/api/1/builds/21837"
}

build_args - (JSON object)

JSON object containing arguments passed to build system to build this artifact.

Warning

The content of this JSON object is not part of the Freshmaker REST API and can change at any time.

Commonly used build_args are:

arches - white-space separated list of architecture the Artifact is built against.
branch - name of the branch from which the Artifact’s source code is taken.
commit - commit hash in source repository from which the Artifact’s source code is taken.
target - Koji target in which the Artifact is built.
retry_count - number describes how many times was Artifact build retried.

build_id - (number): The ID of Artifact Build. For container images (the only supported artifact at this moment), this is the Koji (or Brew) buildContainer task ID. If this field is null, Freshmaker did not submit a buildContainer task (due to some other failure), or Koji failed to return a task ID for some reason.

dep_on - (string): The name. of the Artifact build this Artifact build depends on.

dep_on_id - (number): The ID of the Artifact build this Artifact build depends on.

event_id - (number): The ID of the Event this Artifact Build is part of.

name - (string): The name of this Artifact Build.

odcs_composes - (list of numbers): List of ODCS composes the Freshmaker directly generated and used while building this Artifact build in the build system.

original_nvr - (string): The original (before the rebuild) NVR of Artifact build.

rebuild_reason - (string)

The reason why this artifact is included in the Event. Can be one of:

directly_affected - The Artifact build is directly affected by the Event (for example affected by the CVE) and is allowed by Freshmaker’s configuration.
dependency - The Artifact build is included in the Event just because it is dependency of directly_affected Artifact build.

rebuilt_nvr - (string): The NVR of Artifact build built by Freshmaker.

state - (number)

Number defining the state the Artifact build is currently in:

0 (BUILD) - Artifact build is currently being built in build system.
1 (DONE) - Artifact build has been built successfully.
2 (FAILED) - Artifact build failed to be build.
3 (CANCELED) - Artifact build has been cancelled manually.
4 (PLANNED) - Artifact build is planned to be build.

state_name - (string): Name of the state the Artifact build is currently in. See state for more info.

state_reason - (string): Sentence describing the current state.

time_completed - (datetime): The date and time on which the Artifact Build has been completed.

time_submitted - (datetime): The date and time on which the Artifact build has been moved to PLANNED state.

type - (number)

Type of the Artifact build:

0 (RPM) - Artifact build is an RPM package.
1 (IMAGE) - Artifact build is a container image.
2 (MODULE) - Artifact build is a module.
3 (IMAGE_REPOSITORY) - Artifact build is a container image repository.

type__name - (string): Name of the type of Artifact build. See type for more info.

REST API pagination

When multiple objects are returned by the Freshmaker REST API, they are wrapped in the following JSON which allows pagination:

{
    "items": [
        {JSON_OBJECT},
        ...
    ],
    "meta": {
        "first": "http://freshmaker.localhost/api/1/events/?per_page=10&page=1",
        "last": "http://freshmaker.localhost/api/1/events/?per_page=10&page=14890",
        "next": "http://freshmaker.localhost/api/1/events/?per_page=10&page=2",
        "page": 1,
        "pages": 14890,
        "per_page": 10,
        "prev": null,
        "total": 148898
    }
}

The items list contains the objects JSONs. The meta dict contains metadata about pagination. It is possible to use per_page argument to set the number of objects showed per single page and page to choose the page to show.

HTTP REST API

GET /api/1/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:
- id
- message_id

Status Codes:

200 OK – Requested events are returned.
404 Not Found – Freshmaker event not found.

PATCH /api/1/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:

200 OK – Cancelled event is returned.
400 Bad Request – Action is missing or is unsupported.

GET /api/1/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:
- id
- message_id

Status Codes:

200 OK – Requested events are returned.
404 Not Found – Freshmaker event not found.

POST /api/1/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:

200 OK – A new event was created.
400 Bad Request – The provided input is invalid.

GET /api/1/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/1/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/1/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:

200 OK – A new event was created.
400 Bad Request – The provided input is invalid.