How to Organize API Types

[danehans]

Currently, EG API types reside in 2 locations:

• Envoy Gateway and Envoy Proxy configuration: api/config/v1alpha1.
• Extended functionality: api/v1alpha1.

This makes imports a bit confusing:

import (
	egv1a1 "github.com/envoyproxy/gateway/api/v1alpha1"
	egcfgv1a1 "github.com/envoyproxy/gateway/api/config/v1alpha1"
)

It's unclear what API types are being imported from github.com/envoyproxy/gateway/api/v1alpha1.

[danehans]

From the 5/13/22 EG community call, @youngnick proposes:

I recommend keeping all the types in the version directory (eg v1alpha1), with validation, helper, or utility code in subdirectories.

[danehans]

My recommendation slightly differs from the above. I suggest having separate config and extension API groups. Helper functions, validation, etc. will live within each group for the associated types. This allows versioning the extension types separately from the config types. For example, the EnvoyProxy type can graduate faster than extension API types since they may be more widely used. Additionally, it simplifies transitioning the extension APIs into a separate repo.

Thoughts @youngnick

[zirain]

+1 to egv1 "github.com/envoyproxy/gateway/api/v1alpha1" or egv1alpha1 "github.com/envoyproxy/gateway/api/v1alpha1"

[youngnick]

@danehans, I think that's fine, although I suggest standardizing the import names to make reading the code easier.

[danehans]

@arkodg @AliceProxy @Xunzhuo @skriss please comment if you have issue with the approach in #809 (comment).

[arkodg]

@danehans i think theres a typo in the issue description - Extended functionality: api/v1alpha1
as @zirain suggested I prefer all EG APIs to live under api/v1alpha1 under the same group for now so there are lesser groups to revision

[danehans]

i think theres a typo in the issue description

@arkodg thanks for catching this. I updated the description.

I prefer all EG APIs to live under api/v1alpha1 under the same group for now so there are lesser groups to revision

If our long-term intention is for extensions to live outside of the EG repo, they'll be revisioned separately.