search

netbox-community / go-netbox

The official Go API client for Netbox IPAM and DCIM service.
Other
194 stars 144 forks source link

Version this SDK based on Netbox releases #102

Closed bvandewalle closed 1 year ago

bvandewalle commented 3 years ago

TLDR: Add tags to this SDK that match previous releases of Netbox, so that we can import a version that works based on our version of Netbox.

netbox and go-netbox versioning mismatch:

The crux of the issue here is that Netbox does not seem to fully respect Semantic Versioning. An example (among others) that bit me: Going from 2.6 --> 2.7 , the following API breaking change was introduced:

"status": {
    "value": 1,
    "label": "Active"
},

In NetBox v2.7, it now looks like this:

"status": {
    "value": "active",
    "label": "Active",
    "id": 1
},

As Go, and OpenAPI are statically typed, this results in a predictible unmarshal error if you try to use what is currently on master for go-netbox with Netbox v2.6:

json: cannot unmarshal number into Go struct field PrefixStatus.results.status.value of type string

If API Changes were purely additive in Netbox, this wouldn't be an issue (as defined by SemVer as using the same major version).

Since this SDK is not versioned, there are PR and commits coming in for all version of Netbox. For example, this PR attempts to fix the SDK for the issue above for Netbox v2.6 users: https://github.com/netbox-community/go-netbox/pull/70

As this PR describes, it was initially there, then got overwritten (with the v2.7 changes). After this PR got applied, master went back to v2.6 for a little while, then another PR replaced it with the v2.7 breaking changes again:

How to resolve this

The simplest is to assume that master is always up to date with the latest netbox API. I would suggest making sure that all the PR that get accepted are relevant for the latest netbox API as well.

For previous Netbox version, a tag/label should be added to specific commit that are known to be the latest working commits for those versions. A table of compatibility should then ideally be available. For example, the kubernetes go-client does this pretty well IMO:

https://github.com/kubernetes/client-go#compatibility-matrix

smutel commented 3 years ago

Related to #68

v0ctor commented 1 year ago

The project now follows Semantic Versioning standard so as not to reinvent the wheel. 🤓