search

apigee / registry

The Registry API allows teams to track and manage machine-readable descriptions of APIs.
https://apigee.github.io/registry
Apache License 2.0
147 stars 33 forks source link

Registry server: support implicit tags to access prior revisions #600

Open timburks opened 2 years ago

timburks commented 2 years ago

Currently the registry diff subcommand uses a pattern from git to refer to prior revisions of specs and deployments. Looking back into the revision history, @{-1} refers to the next-to-last revision, @{-2} refers to the revision before that, etc. It seems beneficial to support something like this directly in the API.

However, we probably would not want to use curly (or square) braces around the offset. AIP-162 refers to RFC 1738, which indicates that these braces should be escaped in URLs. I haven't seen anything that specifically forbids usage of these braces. but it seems undesirable to use a delimiter that requires escaping in HTTP transcodings of the API.

A simpler representation might be fine. Since our revision ids are 6 character alphanumeric strings, small integers would not conflict with them, although they would potentially conflict with user-defined tags (unless we prevented users from creating numeric tags, which seems like a good idea regardless). I think the minus sign (dash) is unnecessary and should be omitted, making @1 refer to the next-to-last revision, @2 refer to the revision before that, etc. @0 could be accepted as an identifier for the current revision. I think it would also be fine to adjust this by 1 so that @1 is the current revision, @2 the one before that, etc.

With this, registry diff would drop support for @{-1} and would instead rely on the service to return requested revisions.

timburks commented 2 years ago

@ssvaidyanathan this is related to the implicit latest tag that we discussed. We might also define latest or use the numeric offsets to refer to current/prior revisions.

theganyo commented 2 years ago

It would seem the prior art here is either git - which uses a tilde (eg. branch~2), or programming languages - which generally use a negative array reference counting from the end (eg. array[-2]). Rather than restricting tags or assuming small integers, perhaps we should follow the git model and use the tilde for relative references and only use the @ for direct?

timburks commented 1 year ago

@theganyo, I like that, but it gets into territory covered by AIP-162:

Note: The @ character is selected because it is the only character permitted by RFC 1738 §2.2 for special meaning within a URI scheme that is not already used elsewhere.

theganyo commented 1 year ago

Ok. Without that option on the table, I'd like to understand why you feel "the minus sign (dash) is unnecessary and should be omitted". I feel that using a negative value after the @ would naturally avoid any current values, have a clear precedence in programming languages, and would be more clearly self-documenting and intuitive than a reserved set of positive values.