Could we be consistent naming fields of Entities?

[carlosthe19916]

• If I hit GET /api/v1/package then I get:

{
    "items": [
        {
            "uuid": "f7d25fe0-2f5c-5feb-854f-762b7ecd6527",
            "purl": "pkg://npm/[email protected]",
            "base": {
                "uuid": "41de79a7-d36e-57e2-83ab-984875221b35",
                "purl": "pkg://npm/highlight-words-core"
            },
            "version": {
                "uuid": "f7d25fe0-2f5c-5feb-854f-762b7ecd6527",
                "purl": "pkg://npm/[email protected]",
                "version": "1.2.0"
            }
        }
    ],
    "total": 14054
}

• If I hit GET /api/v1/sbom/{key}/packages I get:

{
    "items": [
        {
            "id": "SPDXRef-008b7ce8-0a74-4140-9625-93645d154c3f",
            "name": "python-syspurpose",
            "purl": [
                "pkg://rpm/redhat/[email protected]_9?arch=s390x"
            ]
        },
    ],
    "total": 445
}

Both endpoints are supposed to give me PACKAGES yet both endpoints are not returning the same data (DTO structure)

An A DTO model should have the exact same fields everywhere it appears.

• If we call something A, then A should have the same fields everywhere. If not, perhaps we should make a distinction in naming entities and instead of A, we need A and B for naming entities.

• If we were modeling a Person DTO that has name, surname. Then I expect a Person to have exactly those fields everywhere regardless of where it comes from. It is hard to deal with situations where if i hit an endpoint the person has name and surname and if I hit another different endpoint the person has firstname, secondname.

• In the case of the packages above. If you think that technically it is correct to return different bodies for packages endpoints then I think we should reconsider our naming and instead of GET /api/v1/package and GET /api/v1/sbom/{key}/packages we have something like GET /api/v1/purls and GET /api/v1/sbom/{key}/package-names. My point is, we can not call 2 things with the same name, and have different DTOs for the same thing

Note: this also makes the remember the discussion about naming Advisory[severity] in one endpoint while we have Advisory[average_severy] in another endpoints. Perhaps, only one of them should be named Advisory, and the other entity is could be renamed as Recommending (just random name). I hope I explained my point

[ctron]

Judging by the URLs I would say you get package and sbom/{key}/package. Translating into "packages" and "packages of an sbom". Which are two different things. And yes, naming is hard.

What worries me a bit is the package vs packages. As that feels like a pattern we should keep aligned.

[bobmcwhirter]

I've been sticking to singulars, to avoid english weird plurals. Cacti, octopode, deer, fish.