goaci

README

ACI client library for Go

---

GoACI is a Go client library for Cisco ACI. It features a simple, extensible API, advanced JSON manipulation, and a backup client for running queries against the backup file.

Getting Started

Installing

To start using GoACI, install Go and go get:

$ go get -u github.com/brightpuddle/goaci

Basic Usage

package main

import "github.com/brightpuddle/goaci"

func main() {
    client, _ := goaci.NewClient("1.1.1.1", "user", "pwd")
    if err := client.Login(); err != nil {
        panic(err)
    }

    res, _ = client.Get("/api/mo/uni/tn-infra")
    println(res.Get("imdata.0.*.attributes.name"))
}

This will print:

infra

Result manipulation

goaci.Result uses GJSON to simplify handling JSON results. See the GJSON documentation for more detail.

res, _ := GetClass("fvBD")
res.Get("0.fvBD.attributes.name").Str // name of first BD
res.Get("0.*.attributes.name").Str // name of first BD (if you don't know the class)

for _, bd := range res.Array() {
    println(res.Get("*.attributes|@pretty")) // pretty print BD attributes
}

for _, bd := range res.Get("#.fvBD.attributes").Array() {
    println(res.Get("@pretty") // pretty print BD attributes
}

Helpers for common patterns

res, _ := GetDn("uni/tn-infra")
res, _ := GetClass("fvTenant")

Query parameters

Pass the goaci.Query object to the Get request to add query paramters:

queryInfra := goaci.Query("query-target-filter", `eq(fvTenant.name,"infra")`)
res, _ := client.GetClass("fvTenant", queryInfra)

Pass as many paramters as needed:

res, _ := client.GetClass("isisRoute",
    goaci.Query("rsp-subtree-include", "relations"),
    goaci.Query("query-target-filter", `eq(isisRoute.pfx,"10.66.0.1/32")`,
)

POST data creation

goaci.Body is a wrapper for SJSON. SJSON supports a path syntax simplifying JSON creation.

exampleTenant := goaci.Body{}.Set("fvTenant.attributes.name", "goaci-example").Str
client.Post("/api/mo/uni/tn-goaci-example", exampleTenant)

These can be chained:

tenantA := goaci.Body{}.
    Set("fvTenant.attributes.name", "goaci-example-a").
    Set("fvTenant.attributes.descr", "Example tenant A")

...or nested:

attrs := goaci.Body{}.
    Set("name", "goaci-example-b").
    Set("descr", "Example tenant B").
    Str
tenantB := goaaci.Body{}.SetRaw("fvTenant.attributes", attrs).Str

Token refresh

Token refresh is handled automatically. The client keeps a timer and checks elapsed time on each request, refreshing the token every 8 minutes. This can be handled manually if desired:

res, _ := client.Get("/api/...", goaci.NoRefresh)
client.Refresh()

Backup client

goACI also features a backup file client for querying ACI .tar.gz backup files. This client partially mirrors the API of the HTTP client. Note that this must be imported separately.

package main

import "github.com/brightpuddle/goaci/backup"

func main() {
    client, _ := goaci.NewBackup("config.tar.gz")

    res, _ := client.GetDn("uni/tn-infra")
    println(res.Get("@pretty"))

    res, _ = client.GetClass("fvBD")
    for _, bd := range res.Get("#.fvBD.attributes").Array() {
        fmt.Priintln(bd)
    }

}

Examples

See the examples.

Documentation

Overview

Package goaci is a a Cisco ACI client library for Go.

Index

• func NoRefresh(req *Req)
• func Query(k, v string) func(req *Req)
• func RequestTimeout(x time.Duration) func(*Client)
• type Body
  • func (body Body) Set(path, value string) Body
  • func (body Body) SetRaw(path, rawValue string) Body
• type Client
  • func NewClient(url, usr, pwd string, mods ...func(*Client)) (Client, error)
  • func (client Client) Get(path string, mods ...func(*Req)) (Res, error)
  • func (client Client) GetClass(class string, mods ...func(*Req)) (Res, error)
  • func (client Client) GetDn(dn string, mods ...func(*Req)) (Res, error)
  • func (client Client) Login() error
  • func (client Client) Post(path, data string, mods ...func(*Req)) (Res, error)
  • func (client Client) Refresh() error
• type Req
  • func NewReq(method, uri string, body io.Reader, mods ...func(*Req)) Req
• type Res

Functions

func NoRefresh

func NoRefresh(req *Req)

NoRefresh prevents token refresh check.

func Query

func Query(k, v string) func(req *Req)

Query sets an HTTP query parameter.

func RequestTimeout

func RequestTimeout(x time.Duration) func(*Client)

RequestTimeout modifies the HTTP request timeout from the default.

Types

type Body

type Body struct {
	Str string
}

Body wraps SJSON for building JSON body strings.

func (Body) Set

func (body Body) Set(path, value string) Body

Set sets a JSON path to a value.

func (Body) SetRaw

func (body Body) SetRaw(path, rawValue string) Body

SetRaw sets a JSON path to a raw string value.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is an HTTP API client.

func NewClient

func NewClient(url, usr, pwd string, mods ...func(*Client)) (Client, error)

NewClient creates a new ACI HTTP client.

func (Client) Get

func (client Client) Get(path string, mods ...func(*Req)) (Res, error)

Get makes a GET request and returns a GJSON result.

func (Client) GetClass

func (client Client) GetClass(class string, mods ...func(*Req)) (Res, error)

GetClass makes a GET request by class and unwraps the results.

func (Client) GetDn

func (client Client) GetDn(dn string, mods ...func(*Req)) (Res, error)

GetDn makes a GET request by DN.

func (Client) Login

func (client Client) Login() error

Login authenticates to the Client.

func (Client) Post

func (client Client) Post(path, data string, mods ...func(*Req)) (Res, error)

Post makes a POST request and returns a GJSON result.

func (Client) Refresh

func (client Client) Refresh() error

Refresh refreshes the authentication token.

type Req

type Req struct {
	// contains filtered or unexported fields
}

Req wraps http.Request for API requests.

func NewReq

func NewReq(method, uri string, body io.Reader, mods ...func(*Req)) Req

NewReq creates a new Req.

type Res

type Res = gjson.Result

Res is an API response returned by client requests.