[enhancement] Allow user defined description when creating an artifact version

This proposal is an alternative solution to the problems described in #1462 and #1534 .

In brief, the 1024 limit at the DB layer of the description field for artifact versions combined with extracting the description from an uploaded OpenAPI/AsyncAPI document effectively limit the “info.description” field in the actual document. This was resolved in ad6ad31cee6e9ea4ea749f10136d37165a5e8033 by truncating the description.

While this allows for creating the artifact version, to make the description useful in the Registry UI, the client must follow up with an update metadata call to change the version and/or artifact description to something usefully rendered in the UI.

In addition to truncating long descriptions extracted from the artifact, I think it would be good to allow the client to optionally define the version description in POST /groups/{groupId}/artifacts/{artifactId}/versions and POST /groups/{groupId}/artifacts. This could happen via an X-Registry-Version-Description header, consistent with the other header-based optional inputs.

[EricWittmann]

Thanks for the request @kilahm - I don’t see any reason not to implement optional user-provided descriptions when uploading a new version. What about the other meta-data fields users can edit, like name and tags? Thoughts on allowing header-based values for those as well?

[EricWittmann]

Thank you everyone for the excellent discussion on this issue!

It sounds like the consensus is still to use separated headers. I think I agree with this, because one goal we should have is to make the most likely use-case as simple as possible. So to that end, here is a proposal:

• X-Registry-Name : ASCII-only value of the name (subject to maxlength limitations as defined by our DDL)
• X-Registry-Description : ASCII-only value of the description (subject to maxlength limitations as defined by our DDL)
• X-Registry-Labels : ASCII-only value of the labels (formatted according to OAI rules for array encoding as suggested by @kilahm )
• X-Registry-Properties : ASCII-only value of the properties (formatted according to OAI rules for object encoding as suggested by @kilahm )

In addition to these headers, I suggest we support the following:

• X-Registry-Name-Encoded : Same as X-Registry-Name but base64 encoded
• X-Registry-Description-Encoded : Same as X-Registry-Description but base64 encoded
• X-Registry-Labels-Encoded : Same as X-Registry-Labels but base64 encoded
• X-Registry-Properties-Encoded : Same as X-Registry-Properties but base64 encoded

Non-encoded headers take precedence over encoded headers if both exist.

Thoughts?