netbox

go-netbox

go-netbox is —to nobody's surprise— the official Go API client for the Netbox IPAM and DCIM service.

This project follows Semantic Versioning. The version of the library built for a Netbox version has the same tag, followed by a hyphen and the build number (an incremental integer), as several versions of the library may exist for the same version of Netbox.

Installation

Use go get to add the library as a dependency to your project. Do not forget to run go mod init first if necessary.

go get github.com/netbox-community/go-netbox/v4

# Or install a specific version
go get github.com/netbox-community/go-netbox/v4@v4.2.2-0

Note: dependencies should be managed with Go modules.

Usage

Instantiate the client

The package has a constructor for creating a client by providing a URL and an authentication token.

package main

import (
	"context"
	"log"

	"github.com/netbox-community/go-netbox/v4"
)

func main() {
	ctx := context.Background()

	c := netbox.NewAPIClientFor("https://demo.netbox.dev", "v3ry$3cr3t")

	log.Printf("%+v", c)
}

Use the client

With the client already instantiated, it is possible to consume any API feature.

For example, to list the first 10 active virtual machines:

package main

import (
	"context"
	"log"

	"github.com/netbox-community/go-netbox/v4"
)

func main() {
	ctx := context.Background()

	c := netbox.NewAPIClientFor("https://demo.netbox.dev", "v3ry$3cr3t")

	res, _, err := c.VirtualizationAPI.
		VirtualizationVirtualMachinesList(ctx).
		Status([]string{"active"}).
		Limit(10).
		Execute()

	if err != nil {
		log.Fatal(err)
	}

	log.Printf("%v", res.Results)
}

See docs or reference for more information on all possible usages.

Development

The project comes with a containerized development environment that may be used on any platform. It is only required to have Git and Docker Desktop (or, separately, Docker and Docker Compose) installed on the machine.

To start the development environment, run the following command.

make

Then, to attach a shell in the container, run the command below.

make shell

Finally, to stop the development environment, run the following command.

make down

Considerations

The library is entirely generated from the Netbox OpenAPI specification using openapi-generator. Therefore, files listed here should not be directly modified, as they will be overwritten in the next regeneration (see next section).

In order to fix a bug in the generated code, the corresponding error in the OpenAPI spec must be fixed. To do so, the following steps may be followed:

1. Optional. Patch the OpenAPI spec in this repo by editing this script, so that a corrected version can be published as soon as possible.
2. Fix the OpenAPI spec in the Netbox repository, either by reporting an issue or by creating a pull request.

Regenerate the library

To update the OpenAPI specification to the latest Netbox version and regenerate the library, run the following command.

make build

If regeneration of the library is needed for a specific Netbox version other than the latest one, pass the corresponding argument.

make build NETBOX_VERSION=3.0.0

In order to obtain the OpenAPI specification, the version of netbox-docker corresponding to the given Netbox version is used. However, it is also possible to provide a specific version of netbox-docker.

make build NETBOX_VERSION=3.0.0 NETBOX_DOCKER_VERSION=1.3.1