/api/v1/package/by-purl/{id} requires an UUID rather than a PURL

carlosthe19916 commented 1 week ago

If the title of the PATH of the endpoint mentions by-url we should expect a PURL being send and not a UUID.

https://github.com/trustification/trustify/blob/3059e6f8109c4bd457a518757413f2a7afb7e43e/modules/fundamental/src/package/endpoints/mod.rs#L72-L78

ctron commented 1 week ago

Well it's the ID of a PURL. We could tweak that actually. The question is, would you have the qualified PURL to make that call?

carlosthe19916 commented 1 week ago

Why do we call a path /api/v1/package/by-purl/{id} if we are not sending a purl but an id? Shouldn't /api/v1/package/by-uuid/{id} be more appropriate? It is like creating an endpoint /person/by-firstname/{passport_number}.

Well it's the ID of a PURL. We could tweak that actually. The question is, would you have the qualified PURL to make that call?

Actually this is a problem I have with the current REST endpoints. I just want to be able to fetch Package by "some key". You can decide what "some key" is as long as that is consistent everywhere. E.g. let me expand a bit please:

`GET /api/v1/package/by-purl` (happy path)

(GET /api/v1/package does not exist anymore only the by-purl endpoint now)

This endpoint provides purl and uuid for each item, therefore I can do GET /api/v1/package/by-purl/{uuid}
GREAT! I am happy because I can navigate from /api/v1/package/by-purl to GET /api/v1/package/by-purl/{uuid}

{
    "items": [
        {
            "uuid": "00001093-5fb8-547a-92ba-348e9f73c2da",
            "purl": "pkg://rpm/redhat/python-oslo-rootwrap@7.1.0-0.20231218164901.0660a66.el9",
            "base": {
                "uuid": "82e13d43-dd26-5e4e-8328-d53cfaf0c311",
                "purl": "pkg://rpm/redhat/python-oslo-rootwrap"
            },
            "version": {
                "uuid": "00001093-5fb8-547a-92ba-348e9f73c2da",
                "purl": "pkg://rpm/redhat/python-oslo-rootwrap@7.1.0-0.20231218164901.0660a66.el9",
                "version": "7.1.0-0.20231218164901.0660a66.el9"
            }
        }
    ],
    "total": 31366
}

`GET /api/v1/sbom/{uuid}/packages` (NOT happy path)

If I fetch the packages from an SBOM using GET /api/v1/sbom/{uuid}/packages then I get a response similar to the json below.

In this case each package of an SBOM only has purl, there is no uuid.
I CAN NOT DO GET /api/v1/package/by-purl/{PURL}. So not good because I can not navigate from a package within an SBOM (the json below) to a package details (GET /api/v1/package/by-purl/{PURL})

{
    "items": [
        {
            "id": "SPDXRef-01600a7f-7bb3-46f8-9fa1-7fdcbcc59d97",
            "name": "glibc-common",
            "version": "2.34-60.el9",
            "purl": [
                "pkg://rpm/redhat/glibc-common@2.34-60.el9?arch=ppc64le"
            ]
        }
    ],
    "total": 70
}

To summarize

All I am saying is that I have no issues using PURLs, UUIDs, or Another Field as a "Key" of a Package, but whatever is the "key" the Backend chooses, that Key must be present every single time the REST endpoints make a reference of it.

This boils down to the same frustration I have with the current endpoints. A Package or any other Entity should have the same fields (fieldA, fieldB,FieldN) everywhere. E.g.

GET /api/v1/package/by-purl gives me back packages that contain uuid and purl. On the other hand:
GET /api/v1/sbom/{uuid}/packages gives me packages only with purl and there is not any uuid

Both endpoints clearly mentions in their URL PATHS the term /package/ but they both clearly generate 2 different models. I believe it was mentioned that packages != package_from_sbom then we should not call them both package.

I understand that this is a bigger discussion currently tracked by https://github.com/trustification/trustify/discussions/478 so I will wait until we have some outcome/conclusion on that discussion. I am just expression a point (probably missing constraints, context, etc.), I will defer to you guys the decision of what is the best thing to do in regards of packages

ctron commented 1 week ago

Why do we call a path /api/v1/package/by-purl/{id} if we are not sending a purl but an id? Shouldn't /api/v1/package/by-uuid/{id} be more appropriate?

Because it is the UUID of a PURL. And not the UUID of a package.

jcrossley3 commented 1 week ago

Wow. So our api requires the client to send an internal identifier of an external identifier? And we're all comfortable with that?

I feel like we're exposing a lot of complexity in our api without much value justifying it.

trustification / trustify