nxapi

Documentation

Overview

Package nxapi provides a JSON-RPC client for Cisco NX-OS devices via NX-API.

Use NewClient to create a client for a given deviceutil.Connection. The client supports both HTTP and HTTPS (selected automatically based on whether a TLS configuration is present) and authenticates with HTTP Basic Auth.

Commands are expressed as plain NX-OS CLI strings and grouped into a Request using NewRequest. A single HTTP POST is made per Request, which may contain one or more commands. Each command in a batch gets its own result in the returned slice.

Errors are surfaced as RPCErrors when NX-OS reports one or more command failures, or as HTTPError for non-2xx responses whose body cannot be parsed as JSON-RPC (for example, a 401 Authorization Required).

Index

• type Client
  • func NewClient(c *deviceutil.Connection, timeout time.Duration) (*Client, error)
  • func (c *Client) Do(ctx context.Context, r Request) ([]json.RawMessage, error)
• type ErrorAction
• type HTTPError
  • func (e *HTTPError) Error() string
• type RPCError
  • func (e *RPCError) Error() string
• type RPCErrors
  • func (e RPCErrors) Error() string
  • func (e RPCErrors) Unwrap() []error
• type Request
  • func NewRequest(cmds ...string) Request
  • func (r Request) Encode() ([]byte, error)
  • func (r Request) WithRollback(a ErrorAction) Request
• type RoundTripFunc
  • func (f RoundTripFunc) RoundTrip(r *http.Request) (*http.Response, error)

Types

type Client

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

Client sends JSON-RPC requests to a Cisco NX-OS device via NX-API. Use NewClient to construct one.

func NewClient

func NewClient(c *deviceutil.Connection, timeout time.Duration) (*Client, error)

NewClient creates a new Client for the given connection. If the connection has a TLS configuration set, HTTPS is used; otherwise HTTP. The underlying HTTP client uses timeout for all requests; a value of 0 means no timeout.

func (*Client) Do

func (c *Client) Do(ctx context.Context, r Request) ([]json.RawMessage, error)

Do sends a Request to the device and returns one json.RawMessage per command, in the same order as the request. If any command fails, Do returns an RPCErrors containing one RPCError per failed command; transport and HTTP errors are returned directly.

type ErrorAction

type ErrorAction string

ErrorAction controls how NX-OS responds when an individual command fails.

const (
	Stop     ErrorAction = "stop-on-error"
	Continue ErrorAction = "continue-on-error"
	Rollback ErrorAction = "rollback-on-error"
)

type HTTPError

type HTTPError struct {
	// Code is the HTTP status code.
	Code int
	// Body contains the raw response body.
	Body []byte
}

HTTPError is returned when the NX-API endpoint responds with a non-2xx status and the body cannot be parsed as a JSON-RPC error.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type RPCError

type RPCError struct {
	// Code is the JSON-RPC error code.
	Code int `json:"code"`
	// Message is the human-readable error description.
	Message string `json:"message"`
	// Data contains additional error context as raw JSON, if present.
	Data json.RawMessage `json:"data"`
}

RPCError represents a single JSON-RPC error returned by NX-OS.

func (*RPCError) Error

func (e *RPCError) Error() string

type RPCErrors

type RPCErrors []*RPCError

RPCErrors is a slice of RPCError values returned when one or more commands in a request fail. It implements the error interface.

func (RPCErrors) Error

func (e RPCErrors) Error() string

Error implements the built-in error interface.

func (RPCErrors) Unwrap

func (e RPCErrors) Unwrap() []error

Unwrap returns the individual RPC errors for use with errors.Is and errors.As.

type Request

type Request []cmd

Request is an ordered list of commands to send in a single JSON-RPC batch.

func NewRequest

func NewRequest(cmds ...string) Request

NewRequest creates a Request from plain CLI command strings.

func (Request) Encode

func (r Request) Encode() ([]byte, error)

Encode serialises the request to JSON.

func (Request) WithRollback

func (r Request) WithRollback(a ErrorAction) Request

WithRollback sets the error action on each command in the request, controlling what NX-OS does if that individual command fails.

type RoundTripFunc

type RoundTripFunc func(*http.Request) (*http.Response, error)

The RoundTripFunc type is an adapter to allow the use of ordinary functions as http.RoundTripper. If f is a function with the appropriate signature, RoundTripFunc(f) is a http.RoundTripper that calls f.

func (RoundTripFunc) RoundTrip

func (f RoundTripFunc) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip returns f(r).