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:
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:
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:
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
}
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:

{
    "images": {
        "foo-1-1": [
            "content-set-1",
            "content-set-2"
        ]
    },
    "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.