github.com/digitalocean/go-netbox@v0.0.2/README.md (about)

     1  go-netbox 
     2  =========
     3  
     4  [![GoDoc](http://godoc.org/github.com/digitalocean/go-netbox?status.svg)](http://godoc.org/github.com/digitalocean/go-netbox) [![Build Status](https://github.com/digitalocean/go-netbox/workflows/main/badge.svg?branch=master)](https://github.com/digitalocean/go-netbox/actions) [![Report Card](https://goreportcard.com/badge/github.com/digitalocean/go-netbox)](https://goreportcard.com/report/github.com/digitalocean/go-netbox)
     5  
     6  Package `netbox` provides an API 2.0 client for [netbox-community's NetBox](https://github.com/netbox-community/netbox)
     7  IPAM and DCIM service.
     8  
     9  This package assumes you are using NetBox 2.0, as the NetBox 1.0 API no longer exists.
    10  
    11  Using the client
    12  ================
    13  
    14  The `github.com/digitalocean/go-netbox/netbox` package has some convenience functions for creating clients with the most common
    15  configurations you are likely to need while connecting to NetBox. `NewNetboxAt` allows you to specify a hostname
    16  (including port, if you need it), and `NewNetboxWithAPIKey` allows you to specify both a hostname:port and API token.
    17  ```golang
    18  import (
    19      "github.com/digitalocean/go-netbox/netbox"
    20  )
    21  ...
    22      c := netbox.NewNetboxAt("your.netbox.host:8000")
    23      // OR
    24      c := netbox.NewNetboxWithAPIKey("your.netbox.host:8000", "your_netbox_token")
    25  ```
    26  
    27  If you specify the API key, you do not need to pass an additional `authInfo` to operations that need authentication, and
    28  can pass `nil`:
    29  ```golang
    30      c.Dcim.DcimDeviceTypesCreate(createRequest, nil)
    31  ```
    32  
    33  If you connect to netbox via HTTPS you have to create an HTTPS configured transport:
    34  ```
    35  package main
    36  
    37  import (
    38  	"os"
    39  
    40  	httptransport "github.com/go-openapi/runtime/client"
    41  	"github.com/digitalocean/go-netbox/netbox/client"
    42  	"github.com/digitalocean/go-netbox/netbox/client/dcim"
    43  
    44  	log "github.com/sirupsen/logrus"
    45  )
    46  
    47  func main() {
    48  	token := os.Getenv("NETBOX_TOKEN")
    49  	if token == "" {
    50  		log.Fatalf("Please provide netbox API token via env var NETBOX_TOKEN")
    51  	}
    52  
    53  	netboxHost := os.Getenv("NETBOX_HOST")
    54  	if netboxHost == "" {
    55  		log.Fatalf("Please provide netbox host via env var NETBOX_HOST")
    56  	}
    57  
    58  	transport := httptransport.New(netboxHost, client.DefaultBasePath, []string{"https"})
    59  	transport.DefaultAuthentication = httptransport.APIKeyAuth("Authorization", "header", "Token "+token)
    60  
    61  	c := client.New(transport, nil)
    62  
    63  	req := dcim.NewDcimSitesListParams()
    64  	res, err := c.Dcim.DcimSitesList(req, nil)
    65  	if err != nil {
    66  		log.Fatalf("Cannot get sites list: %v", err)
    67  	}
    68  	log.Infof("res: %v", res)
    69  }
    70  ```
    71  
    72  Go Module support
    73  ================
    74  
    75  Go 1.16+
    76  
    77  `go get github.com/digitalocean/go-netbox`
    78  
    79  
    80  More complex client configuration
    81  =================================
    82  
    83  The client is generated using [go-swagger](https://github.com/go-swagger/go-swagger). This means the generated client
    84  makes use of [github.com/go-openapi/runtime/client](https://godoc.org/github.com/go-openapi/runtime/client). If you need
    85  a more complex configuration, it is probably possible with a combination of this generated client and the runtime
    86  options.
    87  
    88  The [godocs for the go-openapi/runtime/client module](https://godoc.org/github.com/go-openapi/runtime/client) explain
    89  the client options in detail, including different authentication and debugging options. One thing I want to flag because
    90  it is so useful: setting the `DEBUG` environment variable will dump all requests to standard out.
    91  
    92  Regenerating the client
    93  =======================
    94  
    95  To regenerate the client with a new or different swagger schema, first clean the existing client, then replace
    96  swagger.json and finally re-generate:
    97  ```
    98  make clean
    99  cp new_swagger_file.json swagger.json
   100  make generate
   101  ```