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 tool: make `registry apply` support additional `--parent` types #1039

Open timburks opened 1 year ago

timburks commented 1 year ago

Currently registry apply takes a --parent argument that must be of the form projects/PROJECT/locations/global. Should we expand that to allow more parent types?

If --parent is omitted, we use the configured registry.project and registry.location. If we make the above change, would we accept a parent that is specified relative to those? (e.g. --parent apis/myapi).

If --parent specifies something other than a project/location and there's a parent specified in the Registry YAML metadata, how should we handle conflicts?

User feedback: The YAML works as expected if I provide the path to the API spec for parent: . If we wanted to apply a scorecard to multiple APIs / reuse the YAML, should we be able to specify the parent using the CLI? I haven't been able to figure out how to do that.

TB: We're not supporting that now. I wouldn't rule it out, though.

TB: I would expect that exports and registry get would include the parent in the metadata section, that seems fairly clear.

TB: If there were conflicts between the registry apply --parent and the parent in the file, I think that should be an error (for example, if the command-line parent specifies a spec and the scorecard YAML contains a different parent)... or maybe we should let the command-line argument win and print a warning?

User: I was just thinking of a scenario where a user may want to reuse a scorecard - but who knows if that's even a thing. Either way, there's tools to modify YAML files dynamically and add parent:

TB: right, that's kind of awkward though...

theganyo commented 1 year ago

Because it's clearly not entirely intuitive what --parent should actually do, I think we should keep it as simple and clear as possible by expecting the YAML entities to be properly formed (with parent) or raise an error. For the same reason, I also believe --parent itself should be deprecated in favor of always using the configuration.

If we want to address problematic YAML files that are missing parents and/or reusing entities in various contexts, perhaps we should consider a new command or commands specifically for the purpose of adjusting entity YAML files. But I'm not sure that we need to provide that, given the existence of tools like yq.