API: attaching packages seems to mess up packageIds about oss-attribution-builder HOT 2 CLOSED

It's one of those things that made sense at the time, and in a way still does considering the way data entry is done in the UI. It's not as ergonomic in the API, as you have discovered.

The gist of things is this:

If you supply a package ID (and only a package ID, besides any required usage data), that will get attached to your project, and that's that.

If you supply package information (and no package ID), then a new package will be created. In the UI, these are grouped by package name and version. In a way those are keys for tracking a package. It's OK to have multiple rows with the same package name and version, they represent different revisions of a package. In the UI, if a newer revision is present than what's on your project (determined by the largest package ID), it'll offer to "update" your data. This ends up making more sense at scale with lots of people entering in data for different projects, but a shared package database.

If you supply both a package ID and package information, one of two things will happen:

A. If all information supplied is exactly the same as what's stored in the database, the package will be attached with the same ID. No new package will be created. Or,

B. If any details differ, the API will instead create a new revision of that package and return the new package ID, which will be attached to your project. It's not super smart about this -- if an even older revision was the same, it doesn't really know that.

When using the API, I recommend that you only supply a package ID (+usage data if/as required) if you want to attach an existing package or just package information if you know you want something new.

Nowadays, there are many fantastic projects that catalogue license data and package information. ClearlyDefined is one of them, and would things be re-done we'd probably key off of identifiers like CD's coordinates system. But, legacy. :)

The API docs could certainly be improved here. I'll certainly take pull requests for that, but will also keep this open as a backlog item to make that better.

from oss-attribution-builder.

#44

from oss-attribution-builder.