README
¶
go-catalystcenter
go-catalystcenter is a Go client library for Cisco Catalyst Center. It is based on Nathan's excellent goaci module and features a simple, extensible API and advanced JSON manipulation.
Getting Started
Installing
To start using go-catalystcenter, install Go and go get:
$ go get -u github.com/netascode/go-catalystcenter
Basic Usage
package main
import "github.com/netascode/go-catalystcenter"
func main() {
client, _ := cc.NewClient("https://1.1.1.1", "user", "pwd")
res, _ := client.Get("/dna/intent/api/v2/site")
println(res.Get("response.0.name").String())
}
This will print something like:
Site1
Result manipulation
cc.Result uses GJSON to simplify handling JSON results. See the GJSON documentation for more detail.
res, _ := client.Get("/dna/intent/api/v2/site")
for _, site := range res.Get("response").Array() {
println(site.Get("@pretty").String()) // pretty print sites
}
POST data creation
cc.Body is a wrapper for SJSON. SJSON supports a path syntax simplifying JSON creation.
body := cc.Body{}.
Set("type", "area").
Set("site.area.name", "Area1").
Set("site.area.parentName", "Global")
client.Post("/dna/intent/api/v1/site", body.Str)
Documentation
See the documentation for more details.
Documentation
¶
Overview ¶
Package cc is a Cisco Catalyst Center REST client library for Go.
Index ¶
- Constants
- Variables
- func Asynchronous(req *Req)
- func BackoffDelayFactor(x float64) func(*Client)
- func BackoffMaxDelay(x int) func(*Client)
- func BackoffMinDelay(x int) func(*Client)
- func DefaultMaxAsyncWaitTime(x int) func(*Client)
- func Insecure(x bool) func(*Client)
- func MaxAsyncWaitTime(seconds int) func(*Req)
- func MaxRetries(x int) func(*Client)
- func NoLogPayload(req *Req)
- func RequestTimeout(x time.Duration) func(*Client)
- type Body
- type Client
- func (client *Client) Authenticate() error
- func (client *Client) Backoff(attempts int) bool
- func (client *Client) Delete(path string, mods ...func(*Req)) (Res, error)
- func (client *Client) Do(req Req) (Res, error)
- func (client *Client) Get(path string, mods ...func(*Req)) (Res, error)
- func (client *Client) Login() error
- func (client Client) NewReq(method, uri string, body io.Reader, mods ...func(*Req)) Req
- func (client *Client) Post(path, data string, mods ...func(*Req)) (Res, error)
- func (client *Client) Put(path, data string, mods ...func(*Req)) (Res, error)
- func (client *Client) WaitTask(req *Req, res *Res) (Res, error)
- type Req
- type Res
Constants ¶
const DefaultBackoffDelayFactor float64 = 3
const DefaultBackoffMaxDelay int = 60
const DefaultBackoffMinDelay int = 2
const DefaultDefaultMaxAsyncWaitTime int = 30
const DefaultMaxRetries int = 3
Variables ¶
var SynchronousApiEndpoints = [...]string{
"/dna/intent/api/v1/site",
"/dna/intent/api/v1/global-pool",
}
Functions ¶
func Asynchronous ¶
func Asynchronous(req *Req)
Asynchronous operation. This is only relevant for POST, PUT or DELETE requests.
func BackoffDelayFactor ¶
BackoffDelayFactor modifies the backoff delay factor from the default of 3.
func BackoffMaxDelay ¶
BackoffMaxDelay modifies the maximum delay between two retries from the default of 60.
func BackoffMinDelay ¶
BackoffMinDelay modifies the minimum delay between two retries from the default of 2.
func DefaultMaxAsyncWaitTime ¶ added in v0.1.1
DefaultMaxAsyncWaitTime modifies the maximum wait time for async operations from the default of 30 seconds.
func Insecure ¶
Insecure determines if insecure https connections are allowed. Default value is true.
func MaxAsyncWaitTime ¶ added in v0.1.1
Maximum Asynchronous operation wait time. This is only relevant for POST, PUT or DELETE requests.
func MaxRetries ¶
MaxRetries modifies the maximum number of retries from the default of 3.
func NoLogPayload ¶
func NoLogPayload(req *Req)
NoLogPayload prevents logging of payloads. Primarily used by the Login and Refresh methods where this could expose secrets.
func RequestTimeout ¶
RequestTimeout modifies the HTTP request timeout from the default of 60 seconds.
Types ¶
type Body ¶
type Body struct {
Str string
}
Body wraps SJSON for building JSON body strings. Usage example:
Body{}.Set("name", "ABC").Str
type Client ¶
type Client struct {
// HttpClient is the *http.Client used for API requests.
HttpClient *http.Client
// Url is the Catalyst Center IP or hostname, e.g. https://10.0.0.1:443 (port is optional).
Url string
// Token is the current authentication token
Token string
// Usr is the Catalyst Center username.
Usr string
// Pwd is the Catalyst Center password.
Pwd string
// Maximum number of retries
MaxRetries int
// Minimum delay between two retries
BackoffMinDelay int
// Maximum delay between two retries
BackoffMaxDelay int
// Backoff delay factor
BackoffDelayFactor float64
// Maximum async operations wait time
DefaultMaxAsyncWaitTime int
// Authentication mutex ensures that API login is non-concurrent
AuthenticationMutex *sync.Mutex
// contains filtered or unexported fields
}
Client is an HTTP Catalyst Center client. Always use NewClient to construct it, otherwise requests will panic.
func NewClient ¶
NewClient creates a new Catalyst Center HTTP client. Pass modifiers in to modify the behavior of the client, e.g.
client, _ := NewClient("cc1.cisco.com", "user", "password", RequestTimeout(120))
func (*Client) Authenticate ¶
Login if no token available.
func (*Client) Do ¶
Do makes a request. Requests for Do are built ouside of the client, e.g.
req := client.NewReq("GET", "/dna/intent/api/v2/site", nil)
res, _ := client.Do(req)
func (*Client) Get ¶
Get makes a GET request and returns a gjson result. Before GET is issued, the func ensures that no writing (DELETE/POST/PUT) would run concurrently with it on the entire client (on any path).
Results will be the raw data structure as returned by Catalyst Center, except when it contains an array named "response" with 500 items. In that case the func continues with more GET requests until it can return a concatenation of all the retrieved items from all the pages.
With multiple GETs, the concurrency protection is uninterrupted from the first page until the last page. Protection from concurrent POST or DELETE helps against boundary items being shifted between the pages. Protection from concurrent PUT helps against items moving between pages, when sort becomes unstable due to modification of items. Unfortunately, the protection does not cover any requests from other clients/processes/systems.
func (*Client) Post ¶
Post makes a POST request and returns a GJSON result. Hint: Use the Body struct to easily create POST body data.
type Req ¶
type Req struct {
// HttpReq is the *http.Request obejct.
HttpReq *http.Request
// LogPayload indicates whether logging of payloads should be enabled.
LogPayload bool
// Synchronous indicates whether the request should be performed synchronously.
Synchronous bool
// MaxAsyncWaitTime is the maximum time to wait for an asynchronous operation.
MaxAsyncWaitTime int
}
Req wraps http.Request for API requests.
type Res ¶
Res is an API response returned by client requests. This is a GJSON result, which offers advanced and safe parsing capabilities. https://github.com/tidwall/gjson
Source Files