Task: decide on `POST /api/v1/metadata` payload

[MVrachev]

What is the task about?

Currently, the POST /api/v1/metadata endpoint accepts the following payload:

{
  "settings": {
    "expiration": {
      "root": 365,
      "targets": 365,
      "snapshot": 1,
      "timestamp": 1,
      "bins": 1
    }
  },
  "metadata": {
    "root": {
    ...

What is strange here is that we mention we support a settings dictionary with an expiration value for all roles, but that is not true inside the code:

repository-service-tuf-api/repository_service_tuf_api/metadata.py

Line 21 in 407ffff

metadata: Dict[Literal[Roles.ROOT.value], TUFMetadata]

There are two solutions to this situation:

1. remove the settings dictionary from the example
2. start actually supporting the settings dictionary

We can easily remove the expiration values for all roles except root.
The argument why we would do 2 and why root is hard to remove is that we provide another endpoint GET /api/v1/config where we give information about repository settings to the user including the expiration policy for root. That means that even though we don't actually use this value anywhere we need to store it, so if an organization wants to check their expiration policy for all roles they could.
Now, the problem comes that when we call POST /api/v1/metadata there is a possibility to update the root expiration date (which itself is calculated to a particular date and stored inside root metadata), but what is not stored is how many days from the date of the metadata update ceremony this expiration was increased (or in other words the user choice for expiration policy for root).
One way to fix this problem is to send this new argument settings with information about root expiration as that's the only expiration policy that could be changed with the metadata update ceremony from the CLI (the rest of the expiration policies can be changed with PUT /api/v1/config.
Another solution could be to include this information as unrecognized_field inside the root metadata itself.
The good part is that this is not so visible to the user and won't lead to false conclusions as the existence of a settings argument could.
The only negative is that we don't do that for any other metadata role, but considering root is special in its own rights I think that's a viable solution.

What do you think @kairoaraujo, @lukpueh @KAUTH?

Parent feature

No response

References

• https://repository-service-tuf.github.io/repository-service-tuf-api/#/v1/post_api_v1_metadata__post
• https://repository-service-tuf.github.io/repository-service-tuf-api/#/v1/put_api_v1_config__put
• https://github.com/theupdateframework/python-tuf/blob/a871f648e571d1dbdb979af51be5a18b73772ae4/tuf/api/metadata.py#L754

Code of Conduct

• I agree to follow this project's Code of Conduct