HTTP API to manage relationships between artifacts

GET /api/1.0/artifact-relation

This GET request must take one valid filter as a query parameter. Supported filters are:

• artifact=$ARTIFACT_ID: returns all relations associated to the listed artifact
• target_artifact=$ARTIFACT_ID: returns all relations where the listed artifact is the target of the relations.

This will return JSON data with a list of relations similar to this:

[
    { "id": "$RELATION_ID", "artifact": "$ARTIFACT_ID",
      "type": "$TYPE_OF_RELATION", "target": "$TARGET_ARTIFACT_ID" },
    ...
]

There are various failure modes:

• it can return HTTP 404 Not found in case the artifact ID used in the filter doesn't exist
• it can return HTTP 403 Permission denied if the user is not allowed to view the artifact used for the filter operation
• it can return HTTP 400 Bad request, if there's no valid filter in the query parameters

POST /api/1.0/artifact-relation

This will create a new relation. The relation to be created is described in the JSON data that is provided as input:

{
    "artifact": "$ARTIFACT_ID",
    "type": "$TYPE_OF_RELATION",
    "target": "$TARGET_ARTIFACT_ID"
}

There are various failure modes:

• it can return HTTP 400 Bad Request when the JSON input data is invalid or when the value for $TYPE_OF_RELATION is unknown or when one of the artifact IDs doesn't exist
• it can return HTTP 403 Permission denied if the user does not have write rights on the artifact

In case of success, it will return HTTP 201 with a copy of the JSON representation of the created relation (augmented with the "id" that has been attributed to the relation).

DELETE /api/1.0/artifact-relation/$ID

This will remove the relation referenced by $ID.

There are various failure modes:

• it can return HTTP 404 Not found in case the relation ID doesn't exist
• it can return HTTP 403 Permission denied if the user does not have write rights on the artifact

Types of relations

We should define the relationships that we want to support and the meaning we give to them. It's hard to be forward looking here, but at the same time, we have some clear needs to fill, at least in terms of retention policy (we want some artifacts to be tied to others so that they disappear together with them), and maybe of license compliance (think Built-Using field of Debian) or reproducibility (same constraint but for different reasons). So here's my initial proposal:

• extends: when the artifact is downloaded, the target artifact is also downloaded because this one has no use without it
  • Ex: a .changes files extends a source package and a binary package
• relates-to: the lifetime of the artifact is tied to the lifetime of the target artifact because this one is useless or has no meaning without the target
  • Ex: lintian analysis of a package, it should disappear when the package disappear too
• built-using: the target artifact has been used to build this artifact and should be kept for as long as this one is kept (for license compliance or other reasons)