Metadata API: Consider removing 'update()' methods #1627

[edited on 12/20/2021: Mention ".json" bias]
[edited on 11/10/2021: Point to #1230]

Description of issue or feature request:

The Metadata API classes for top-level roles Targets, Timestamp and Snapshot each have an update method. They have been criticised in several places (#1193 (comment) pp, #1223 (comment) pp, #1620 (comment)).

More specifically the following doubts have been expressed:

• update is an ambiguous name, e.g. does it stand for "update some attributes of object" or for "update object in the course of a repository update"? - New metadata API: add MetadataInfo and TargetFile classes #1223 (comment)

• update is unspecific about which attributes are updated - New API: Revise "update" methods in tuf/api/metadata.py #1230

• Is update a repository action only and should thus be in a repository controller and not on the Metadata API, which is also used by the client? - How much metadata behaviour should be implemented on their classes? #1134

• [e.g. Targets.update()] is literally a one-liner that modifies a public dict attribute: we could document doing that instead and have a smaller API surface. - Add missing method args docs in metadata API #1620 (comment)

• [e.g. Targets.update()] inserts or replaces the TargetFile... but a Targets handles both TargetFiles and delegations: what if I wanted to modify delegations instead? is it obvious that TargetFile needs a function but delegations do not? - Add missing method args docs in metadata API #1620 (comment)

• [e.g. Snapshot.update()] is opinionated in regards to the file extension of the targets metadata to be updated with, i.e. it assumes that it is .json. The rest of the metadata API also often defaults to json, but allows a caller to override, which is not the case here.

Current behavior:

• purpose of method is unclear
• method name is ambiguous

Expected behavior:

• Make a better case for the purpose and names of methods and document it, or replace/remove.