restconf

README

go-restconf

go-restconf is a Go client library for RESTCONF devices. 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-restconf, install Go and go get:

$ go get -u github.com/netascode/go-restconf

Basic Usage

package main

import "github.com/netascode/go-resconf"

func main() {
    client, _ := restconf.NewClient("https://1.1.1.1", "user", "pwd", true)

    res, _ := client.GetData("Cisco-IOS-XE-native:native")
    println(res.Get("Cisco-IOS-XE-native:native.hostname").String())
}

This will print for example:

ROUTER-1

Result manipulation

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

res, _ := client.GetData("Cisco-IOS-XE-native:native/interface/GigabitEthernet")
println(res.Get("Cisco-IOS-XE-native:GigabitEthernet.0.name").String()) // name of first interface

for _, int := range res.Get("Cisco-IOS-XE-native:GigabitEthernet").Array() {
    println(int.Get("@pretty").Raw) // pretty print interface attributes
}

Helpers for common patterns

res, _ := client.GetData("Cisco-IOS-XE-native:native/hostname")
res, _ := client.DeleteData("Cisco-IOS-XE-native:native/banner/login/banner")

Query parameters

Pass the restconf.Query object to the Get request to add query parameters:

queryConfig := restconf.Query("content", "config")
res, _ := client.GetData("Cisco-IOS-XE-native:native", queryConfig)

Pass as many parameters as needed:

res, _ := client.GetData("Cisco-IOS-XE-native:native",
    restconf.Query("content", "config"),
    restconf.Query("depth", "1"),
)

POST data creation

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

exampleUser := restconf.Body{}.Set("Cisco-IOS-XE-native:username.name", "test-user").Str
client.PostData("Cisco-IOS-XE-native:native", exampleUser)

These can be chained:

user1 := restconf.Body{}.
    Set("Cisco-IOS-XE-native:username.name", "test-user").
    Set("Cisco-IOS-XE-native:username.description", "My Test User")

...or nested:

attrs := restconf.Body{}.
    Set("name", "test-user").
    Set("description", "My Test User").
    Str
user1 := restconf.Body{}.SetRaw("Cisco-IOS-XE-native:username", attrs).Str

Documentation

See the documentation for more details.

Documentation

Overview

Package restconf is a RESTCONF (RFC 8040) client library for Go.

Index

• Constants
• func BackoffDelayFactor(x float64) func(*Client)
• func BackoffMaxDelay(x int) func(*Client)
• func BackoffMinDelay(x int) func(*Client)
• func MaxRetries(x int) func(*Client)
• func Query(k, v string) func(req *Req)
• func RequestTimeout(x time.Duration) func(*Client)
• type Body
  • func (body Body) Res() Res
  • func (body Body) Set(path, value string) Body
  • func (body Body) SetRaw(path, rawValue string) Body
• type Client
  • func NewClient(url, usr, pwd string, insecure bool, mods ...func(*Client)) (Client, error)
  • func (client *Client) Backoff(attempts int) bool
  • func (client *Client) DeleteData(path string, mods ...func(*Req)) (Res, int, error)
  • func (client *Client) Do(req Req) (Res, int, error)
  • func (client *Client) GetData(path string, mods ...func(*Req)) (Res, int, error)
  • func (client Client) NewReq(method, uri string, body io.Reader, mods ...func(*Req)) Req
  • func (client *Client) PatchData(path, data string, mods ...func(*Req)) (Res, int, error)
  • func (client *Client) PostData(path, data string, mods ...func(*Req)) (Res, int, error)
  • func (client *Client) PutData(path, data string, mods ...func(*Req)) (Res, int, error)
• type Req
• type Res

Constants

const (
	DefaultMaxRetries         int     = 2
	DefaultBackoffMinDelay    int     = 4
	DefaultBackoffMaxDelay    int     = 60
	DefaultBackoffDelayFactor float64 = 3
	RestconfDataEndpoint      string  = "/data"
)

Functions

func BackoffDelayFactor

func BackoffDelayFactor(x float64) func(*Client)

BackoffDelayFactor modifies the backoff delay factor from the default of 3.

func BackoffMaxDelay

func BackoffMaxDelay(x int) func(*Client)

BackoffMaxDelay modifies the maximum delay between two retries from the default of 60.

func BackoffMinDelay

func BackoffMinDelay(x int) func(*Client)

BackoffMinDelay modifies the minimum delay between two retries from the default of 4.

func MaxRetries

func MaxRetries(x int) func(*Client)

MaxRetries modifies the maximum number of retries from the default of 2.

func Query

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

Query sets an HTTP query parameter.

client.GetData("Cisco-IOS-XE-native:native", restconf.Query("content", "config"))

Or set multiple parameters:

client.GetData("Cisco-IOS-XE-native:native",
  restconf.Query("content", "config"),
  restconf.Query("depth", "1"))

func RequestTimeout

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

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(Cisco-IOS-XE-native:native.hostname", "ROUTER-1").Str

func (Body) Res

func (body Body) Res() Res

Res creates a Res object, i.e. a GJSON result object.

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. This is primarily used for building up nested structures, e.g.:

Body{}.SetRaw("Cisco-IOS-XE-native:native", Body{}.Set("hostname", "ROUTER-1").Str).Str

type Client

type Client struct {
	// HttpClient is the *http.Client used for API requests.
	HttpClient *http.Client
	// Url is the device url.
	Url string
	// Usr is the device username.
	Usr string
	// Pwd is the device password.
	Pwd string
	// Insecure determines if insecure https connections are allowed.
	Insecure bool
	// 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
	// Discovered RESTCONF API endpoint
	RestconfEndpoint string
}

Client is an HTTP RESTCONF client. Use restconf.NewClient to initiate a client. This will ensure proper cookie handling and processing of modifiers.

func NewClient

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

NewClient creates a new RESTCONF HTTP client. Pass modifiers in to modify the behavior of the client, e.g.

client, _ := NewClient("https://10.0.0.1", "user", "password", true, RequestTimeout(120))

func (*Client) Backoff

func (client *Client) Backoff(attempts int) bool

Backoff waits following an exponential backoff algorithm

func (*Client) DeleteData

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

DeleteData makes a DELETE request and returns a GJSON result.

func (*Client) Do

func (client *Client) Do(req Req) (Res, int, error)

Do makes a request. Requests for Do are built ouside of the client, e.g.

req := client.NewReq("GET", "Cisco-IOS-XE-native:native/hostname", nil)
res, _ := client.Do(req)

func (*Client) GetData

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

GetData makes a GET request and returns a GJSON result.

func (Client) NewReq

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

NewReq creates a new Req request for this client.

func (*Client) PatchData

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

PatchData makes a PATCH request and returns a GJSON result. Hint: Use the Body struct to easily create PATCH body data.

func (*Client) PostData

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

PostData makes a POST request and returns a GJSON result. Hint: Use the Body struct to easily create POST body data.

func (*Client) PutData

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

PutData makes a PUT request and returns a GJSON result. Hint: Use the Body struct to easily create PUT body data.

type Req

type Req struct {
	// HttpReq is the *http.Request object.
	HttpReq *http.Request
}

Req wraps http.Request for API requests.

type Res

type Res = gjson.Result

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