Equinix Metal Go bindings

[displague]

How should packngo clients change to work with Equinix Metal?

---

The conversation below originates on packethost/terraform-provider-packet#279 (comment)

equinix-go-sdk?

There are a few rename options, github.com/equinixmetal/equinix-metal-go/ or perhaps equinixmetal/equinix-metal-sdks/go (one repo with multiple providers, it might be hard to get Ruby, Python, Java/Maven, Go, NPM, and other tools to agree on the root directory structure, but this would make for a convenient way to maintain the various bindings.)

We may want to keep packngo alone and only redirect it to a new org. This will prevent breakage if we prefer to split the project up into concise packages (and not park everything in the root).

If we establish a new project, metal/v1/ (https://blog.golang.org/v2-go-modules) might be a convenient base path.

• metal/v1/clients/metal/metal.go
• metal/v1/clients/metadata/metadata.go
• metal/v1/services/device/device.go
• metal/v1/models/device/device.go

This layout isn't something I've put too much thought into. One drawback, compared to the current design, is that you would need to specify different package names and import various packages, potentially with the same name, where a single packngo was sufficient before.

Ultimately, it may be better to start the new project with Swagger generated models and services and layer helpers on top of that.

[displague]

Updating this issue with some developments over the past two years.

A good bit of experimentation has happened at https://github.com/t0mk/gometal. Here @t0mk and I collaborated on go-swagger and then openapitools generated Go bindings. Initially, this required several patches to the spec, these are kept in the Github project. The patches that we maintain now work around a limitation of the openapitools generator, it can not handle endpoints assigned to multiple tags (or perhaps this can be worked around another way).

Removing documentation, meta files, and generated files, the gometal project boils down to a reusable Makefile - https://github.com/t0mk/gometal/blob/main/Makefile.

Generally, this SDK is in a good place. Its weaknesses are derived from missing definitions or inaccuracies in the API spec. These weaknesses are being addressed internally now, rather than through patches. That said, spec patches made to gometal can be ported to the public spec.

Since this issue was opened, the Terraform provider for Equinix Metal has been unified into the Terraform provider Equinix. It would now be beneficial to unify API Specs and SDKs for ease of management and usability.

Today we have github.com/equinix/client-go, github.com/equinix/ne-go, github.com/equinix/ecx-go, and github.com/packethost/packngo. All of these are hand maintained.

I'd like to see us move towards a consolidated single repository, perhaps the following:
github.com/equinix/equinix-go

• metal/v1/
• ne/v1
• fabric/v4
• ecx/v2

This pattern does introduce potential problems with API breaking changes potentially being introduced within any of these individual APIs. The versioning schemes could be confusing, API resource path versions versus public Go module and Semver versions.

Each of these Equinix APIs has an OpenAPI spec available, most in OAS3 or offering OAS3 soon. If we can consume and require accuracy in these specs, we should be able to remodel the Equinix Terraform provider (among other tools) on generated SDKs. https://developer.equinix.com/catalog. (The path to the OAS3 spec file is patterned in such a way that we can fetch the spec via URL without needing to download the zip file and unarchive it, we can have a direct unzipped URL for each spec.)

The gometal Makefile pattern could be used to generate SDK paths for each of the APIs available. This would give us some isolation between clients, but it will also give us repeated code and lack of sharing around common components - like URLs and authentication. We may benefit from sharing the common 'client' (HTTP client) code between all of the generated SDKs. This was the intent of equinix/client-go, for example.

I've done a little bit of tooling against OAS3 specs, https://github.com/displague/openapi-axe/blob/main/main.go. Following this work, I believe we may want to consider combining all of the available specs into a single spec and generating a client from that, if only as an experiment.