feat(proposals): add nested API objects

[jbrockopp]

Co-authored-by: @ecrupper

Please vote for which option you prefer the most:

• Option 1
• Option 2

[cognifloyd]

I prefer option 1 as Vela has not released v1 yet, so, based on semantic versioning, API changes should be expected.

[cognifloyd]

I don't think favorites should be exposed in most cases. It seems to me that that's a user preference that the UI (or CLI) should be able to request for the current user, but nobody/nothing else needs it.

What purpose does exposing a user's favorites to a build (in env vars) or in these API calls have? Is there a use case I haven't considered?

[jbrockopp]

I don't think we necessarily meant to propose that the owner field has to have the favorites displayed.

More so, I think we simply took the existing user API definition:

// User is the library representation of a user.
//
// swagger:model User
type User struct {
	ID           *int64    `json:"id,omitempty"`
	Name         *string   `json:"name,omitempty"`
	RefreshToken *string   `json:"-"`
	Token        *string   `json:"-"`
	Hash         *string   `json:"-"`
	Favorites    *[]string `json:"favorites,omitempty"`
	Active       *bool     `json:"active,omitempty"`
	Admin        *bool     `json:"admin,omitempty"`
}

And removed the fields that can't be returned (- in JSON field tags).

Regarding implementation, we can certainly ensure that favorites is not returned to minimize payload size.

[cognifloyd]

Here's an interesting approach to API compatibility guarantees:
Vault clarifies that /v1 is not finalized yet in the docs:

Backwards compatibility: At the current version, Vault does not yet promise backwards compatibility even with the v1 prefix. We'll remove this warning when this policy changes. At this point in time the core API (that is, sys/ routes) change very infrequently, but various secrets engines/auth methods/etc. sometimes have minor changes to accommodate new features as they're developed.

https://www.vaultproject.io/api-docs

We could copy that approach and add a note to the docs about compatibility.

[chrispdriscoll]

Per monthly review of open PRs, the Vela Admins will keep this proposal open until PRs are raised.

[plyr4]

gorm preload came in clutch

[KellyMerrick]

lgtm