Path to 1.0.0 - upcoming breaking changes

[AlexGustafsson]

Cupdate will eventually hit 1.0.0 and with that comes some breaking changes in order to clean up known issues and ensure the foundation for a stable, non-breaking future of Cupdate.

For now, this issue tracks things we probably want to change before 1.0.0 in no particular order.

API changes

Image API referencing

Change how an image is referenced in the API.

/images/ghcr/io/alexgustafsson/cupdate -> ghcr.io/alexgustafsson/cupdate:latest
/images/mongo -> mongo:latest
/images/mongo?tag=1.0.0 -> mongo:1.0.0
/images/foregjo?tag=13.0.3-rootless -> foregjo:13.0.3-rootless
/images/registry/home/internal/zot?digest=13.0.0

The same could probably go for the other endpoints, like descriptions, graphs, release notes, vulnerabilities etc. etc.

We could probably link to the other resources from the main image resource, only including what's known to work around the (intended) 404s we currently get from the Web UI.

A potential issue with this is how we would handle an ambiguous request like ?tag=1.0.0 where there are two different digests in use. Maybe simply return 300 Multiple Choices if there are multiple matching versions?

Name change?

We could change the name from image to manifest to better follow OCI naming conventions.

Release notes API

To allow for release notes between image versions (say you upgrade from v1.0.0 to v1.3.0), decouple release notes with an image and let those be fetched independently? A range would only work for semantic releases, so the image resource still needs a way to reference the latest release?

# could return a link to the previous release as well, to let the client walk the releases?
/release-notes/mongo?tag=1.0.0

/images/scans

This should probably just be a POST on /workflows/mongo?tag=1.0.0&digest=sha256:xxx instead?

HATEOAS / HAL

Sometimes frowned upon, but for our use case HATEOAS + HAL seems excellent: https://www.ietf.org/archive/id/draft-kelly-json-hal-11.html. It would allow us to decouple different sources, link to them and embed them as needed. It could simplify the UI API client (especially for pagination?).

{
  "name": "ghcr.io/alexgustafsson/cupdate",
  "tag": "1.0.0",
  "digest": "sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0",
  "created": "2025-12-28T16:38:35+01:00",
  "lastModified": "2025-12-28T16:38:35+01:00",
  "_embedded": {
    "tags": {
      "tags": [
        "attestation",
        "deployment",
        "github",
        "namespace:cupdate",
        "sbom",
        "up-to-date",
        "vulnerability:medium"
      ],
      "_links": {
        "self": {
          "href": "/tags/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
        }
      }
    },
    "annotations": {
      "annotations": {
        "org.opencontainers.image.created": "2025-11-25T15:42:02+00:00",
        "org.opencontainers.image.description": "Cupdate keeps track of image updates.",
        "org.opencontainers.image.licenses": "MIT",
        "org.opencontainers.image.revision": "v0.22.2-63-ge02c9ea",
        "org.opencontainers.image.source": "https://github.com/AlexGustafsson/cupdate",
        "org.opencontainers.image.title": "Cupdate",
        "org.opencontainers.image.version": "0.23.0-beta.1"
      },
      "latestAnnotations": {
        "org.opencontainers.image.created": "2025-11-25T15:42:02+00:00",
        "org.opencontainers.image.description": "Cupdate keeps track of image updates.",
        "org.opencontainers.image.licenses": "MIT",
        "org.opencontainers.image.revision": "v0.22.2-63-ge02c9ea",
        "org.opencontainers.image.source": "https://github.com/AlexGustafsson/cupdate",
        "org.opencontainers.image.title": "Cupdate",
        "org.opencontainers.image.version": "0.23.0-beta.1"
      },
      "_links": {
        "self": {
          "href": "/annotations/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
        }
      }
    },
    "vulnerabilities": {
      "total": 10,
      "_links": {
        "self": {
          "href": "/vulnerabilities/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
        }
      }
    }
  },
  "_links": {
    "curie": {
      "href": "https://github.com/AlexGustafsson/cupdate/blob/main/docs/config.md#{rel}",
      "name": "cupdate",
      "templated": true
    },
    "self": {
      "href": "/images/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    },
    "cupdate:tags": {
      "href": "/tags/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    },
    "cupdate:annotations": {
      "href": "/vulnerabilities/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    },
    "cupdate:vulnerabilities": {
      "href": "/vulnerabilities/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    },
    "cupdate:sbom-attestations": {
      "href": "/sbom-attestations/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    },
    "cupdate:provenance-attestations": {
      "href": "/provenance-attestations/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    },
    "cupdate:scorecard": {
      "href": "/scorecards/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    },
    "cupdate:description": {
      "href": "/descriptions/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    },
    "cupdate:graph": {
      "href": "/graphs/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    },
    "cupdate:release-notes": {
      "href": "/release-notes/ghcr.io/alexgustafsson/cupdate?tag=1.0.0&digest=sha256:69e0388d5a891fe5b64bb661755e7e1ec20b36e4544f8a8ea7cb1a672f72aed0"
    }
  }
}

Workflows

We should take advantage of the support for various workflows by having a fast workflow and a full workflow. The fast could get the bare minimum information for the image to appear in the UI, while the full is essentially what we have today. That would eliminate the need to wait for a long time until images are indexed.