[GH-ISSUE #483] Public Interafce redesing #129

New issue

Open

opened 2026-02-28 00:40:41 +03:00 by kerem · 2 comments

kerem commented

2026-02-28 00:40:41 +03:00

Owner

Originally created by @Tinyblargon on GitHub (Oct 18, 2025).
Original GitHub issue: https://github.com/Telmate/proxmox-api-go/issues/483

Currently we have a lot of public functions, lots of them are functions on types.
But in my opinion we don't have consistent way to interact with any of those functions.

My proposal is to introduce the following structure. Everything flows out of the Client, we have sub categories like Guest and QemuGuest, which then have functions to interact with the API.

type ClientConfig struct {
}

func (c ClientConfig) New() (*ClientNewNew, error) {
	client := &clientAPI{}
	return &ClientNewNew{
		Guest:     &guestInterface{c: client},
		QemuGuest: &qemuGuestInterface{c: client},
	}, nil
}

type ClientNewNew struct {
	Guest     GuestInterface
	QemuGuest QemuGuestInterface
}

type (
	// Interface to interact with Qemu and Lxc guests.
	GuestInterface interface {
		List(context.Context) (RawGuestResources, error)
	}
	guestInterface struct {
		c clientApiInterface
	}
)

func (i guestInterface) List(ctx context.Context) (RawGuestResources, error) {
	return nil, nil
}

type (
	// Interface to interact with Qemu guests.
	QemuGuestInterface interface {
		Create(context.Context, ConfigQemu) error
		Start(context.Context, VmRef) error
	}
	qemuGuestInterface struct {
		c clientApiInterface
	}
)

func (i *qemuGuestInterface) Create(ctx context.Context, config ConfigQemu) error {
	return nil
}

func (i *qemuGuestInterface) Start(ctx context.Context, guest VmRef) error {
	return nil
}

Originally created by @Tinyblargon on GitHub (Oct 18, 2025). Original GitHub issue: https://github.com/Telmate/proxmox-api-go/issues/483 Currently we have a lot of public functions, lots of them are functions on types. But in my opinion we don't have consistent way to interact with any of those functions. My proposal is to introduce the following structure. Everything flows out of the `Client`, we have sub categories like `Guest` and `QemuGuest`, which then have functions to interact with the API. ```go type ClientConfig struct { } func (c ClientConfig) New() (*ClientNewNew, error) { client := &clientAPI{} return &ClientNewNew{ Guest: &guestInterface{c: client}, QemuGuest: &qemuGuestInterface{c: client}, }, nil } type ClientNewNew struct { Guest GuestInterface QemuGuest QemuGuestInterface } type ( // Interface to interact with Qemu and Lxc guests. GuestInterface interface { List(context.Context) (RawGuestResources, error) } guestInterface struct { c clientApiInterface } ) func (i guestInterface) List(ctx context.Context) (RawGuestResources, error) { return nil, nil } type ( // Interface to interact with Qemu guests. QemuGuestInterface interface { Create(context.Context, ConfigQemu) error Start(context.Context, VmRef) error } qemuGuestInterface struct { c clientApiInterface } ) func (i *qemuGuestInterface) Create(ctx context.Context, config ConfigQemu) error { return nil } func (i *qemuGuestInterface) Start(ctx context.Context, guest VmRef) error { return nil } ```

kerem commented

2026-02-28 00:40:41 +03:00

Author

Owner

@NemoDacremont commented on GitHub (Oct 19, 2025):

I think this is an interesting way of dividing things that could work well, however I have a few concerns with it.

First, instead of passing the client in every function like now, we'll pass the config of every element, I wonder how much we're gaining on that side.

Second is, I feel like this is a quite big refactor and would be time-consuming. I feel like this isn't worth the investment right now and there are more important things to do

I don't really like testing my projects, but I think this is important in the case of an SDK, especially since it seems there are issues with proxmox v9 (like in terraform provider issues). This is why I think fixing the different tests is more important, and I'll try to continue helping with it.

I also think it would be good to move all the features from the legacy CLI to the new one, and make the new one the default (and maybe remove the legacy code?). I think the current state of the CLI is quite confusing, and I really prefer the new one.

I hope I didn't sound rude, I just wanted to share my thoughts with your proposal

Also, I don't want to create too many PR at the same time to avoid overwhelming you with reviews, would you prefer that I mention you when I would like your feedback ?

@NemoDacremont commented on GitHub (Oct 19, 2025): I think this is an interesting way of dividing things that could work well, however I have a few concerns with it. First, instead of passing the client in every function like now, we'll pass the config of every element, I wonder how much we're gaining on that side. Second is, I feel like this is a quite big refactor and would be time-consuming. I feel like this isn't worth the investment right now and there are more important things to do I don't really like testing my projects, but I think this is important in the case of an SDK, especially since it seems there are issues with proxmox v9 (like in terraform provider issues). This is why I think fixing the different tests is more important, and I'll try to continue helping with it. I also think it would be good to move all the features from the legacy CLI to the new one, and make the new one the default (and maybe remove the legacy code?). I think the current state of the CLI is quite confusing, and I really prefer the new one. I hope I didn't sound rude, I just wanted to share my thoughts with your proposal Also, I don't want to create too many PR at the same time to avoid overwhelming you with reviews, would you prefer that I mention you when I would like your feedback ?

kerem commented

2026-02-28 00:40:41 +03:00

Author

Owner

@Tinyblargon commented on GitHub (Oct 19, 2025):

@NemoDacremont My biggest concert currently is that it's really difficult for a new user to figure out what to call. Some things are normal functions, some are part of struct, some of an alias type. There isn't a good way to discover the project through your IDEs auto completion.

Might be better to do this at a later time tho, when more behaviors are defined.

Also all the small PRs are preferred, if something holds up one PR there isn't a lot of code waiting and gaining merge conflicts.

@Tinyblargon commented on GitHub (Oct 19, 2025): @NemoDacremont My biggest concert currently is that it's really difficult for a new user to figure out what to call. Some things are normal functions, some are part of struct, some of an alias type. There isn't a good way to discover the project through your IDEs auto completion. Might be better to do this at a later time tho, when more behaviors are defined. Also all the small PRs are preferred, if something holds up one PR there isn't a lot of code waiting and gaining merge conflicts.