proposal: thing-model-catalog: rework REST API to allow for attachments functionality

[alexbrdn]

API for TM Attachments

Context

Adding attachments functionality to TMC necessitates providing APIs for reading lists of attachments associated with an inventory TM name and/or a TM ID.
It is reasonable to expect that in the future, more than just the list of attachments might be associated with those and need to be readable via the API. We'll call this TM metadata/TM name metadata for now.

Observations/Requirements

• there is no endpoint to request the metadata for a single TM a.t.m. The only way to get it, is to request the versions of an inventory entry and search through the list for the matching id.
• we need unambiguous endpoints for requesting metadata (including list of attachments) for a TM name and a single TM ID. if these endpoints are mixed in one like /inventory/{tmNameOrId}, then the return type of this endpoint is ambiguous
• these endpoints should not conflict with the endpoint for fetching the latest version of a TM by id or fetch name (which is not necessarily the same as TM name, as it can include a [partial] semver)
• we need also the same for PUT/GET/DELETE of attachment content for a TM name and a single TM id
• the endpoint /inventory/{name}/.versions returns an almost complete subset of the response to /inventory/{name} and can be removed

Decision

We shall split some endpoints to clearly separate the TM names from TMs in the APIs and introduce the endpoints for operations on attachment content. We shall also clearly label the endpoints for getting the latest version of a TM by fetch name.
The endpoint /inventory/{name}/.versions will be removed.

Proposed Endpoints

• GET /thing-models/.latest/{fetchName} -> content of the latest version. fetchName = ID | (TMName [:Semver part]). (!) moved from /thing-models/{idOrName}
• GET /inventory/.latest/{fetchName} -> metadata of the latest version
• GET /thing-models/{tmid} -> content of TM. (!) replaces /thing-models/:idOrName, doesn't work with fetch names
• GET /inventory/{tmid} -> inventory data for the version. (!) replaces /inventory/:name
• GET /inventory/.tmname/{tmname} -> inventory data for the TM name. (!) moved from /inventory/{name}
• PUT/GET/DELETE /thing-models/{id}/.attachments/{attachmentName} -> TM's attachment content
• PUT/GET/DELETE /thing-models/.tmname/{tmname}/.attachments/{attachmentName} -> TM name's attachment content

Consequences

This proposal includes some incompatible changes to the REST API, which are marked by (!) above. It defines a clear separation between requests for TM metadata (inventory) and requests for content of TMs and attachments.

[alexbrdn]

EDIT: replaced mentions of namespace with TM name

[alexbrdn]

EDIT: replace {id} with {tmid} in route definitions; propose to remove /inventory/{name}/.versions endpoint