rest

README

Equinix REST client

Equinix REST client written in Go. Implementation is based on Resty client.

---

Purpose

Purpose of this module is to wrap Resty REST client with Equinix specific error handling. In addition, module adds support for paginated query requests.

Module is used by other Equinix client libraries, like ECX Fabric Go client or Network Edge Go client.

Features

• parses Equinix standardized error response body contents
• GetPaginated function queries for data on APIs with paginated responses. Pagination options can be configured by setting up attributes of PagingConfig

Usage

1. Get recent equinix/rest-go module

   go get -d github.com/equinix/rest-go
   

2. Create new Equinix REST client with default HTTP client

   import (
       "context"
       "net/http"
       "github.com/equinix/rest-go"
   )
   
   func main() {
     c := rest.NewClient(
          context.Background(),
          "https://api.equinix.com",
          &http.Client{})
   }
   

3. Use Equinix HTTP client with Equinix APIs

    respBody := api.AccountResponse{}
    req := c.R().SetResult(&respBody)
    if err := c.Execute(req, "GET", "/ne/v1/device/account"); err != nil {
     //Equinix application error details will be included
     log.Printf("Got error: %s", err) 
    }
   

Debugging

Debug logging comes from Resty client and logs request and response details to stderr.

Such debug logging can be enabled by setting up EQUINIX_REST_LOG environmental variable to DEBUG

Documentation

Overview

Package rest implements Equinix REST client

Index

• Constants
• type ApplicationError
  • func (e ApplicationError) Error() string
• type Client
  • func NewClient(ctx context.Context, baseURL string, httpClient *http.Client) *Client
  • func (c *Client) Do(method string, path string, req *resty.Request) (*resty.Response, error)
  • func (c *Client) Execute(req *resty.Request, method string, path string) error
  • func (c Client) GetOffsetPaginated(path string, result interface{}, conf *OffsetPaginationConfig) ([]interface{}, error)
  • func (c Client) GetPaginated(path string, result interface{}, conf *PagingConfig) ([]interface{}, error)
  • func (c *Client) SetPageSize(pageSize int) *Client
• type Error
  • func (e Error) Error() string
• type OffsetPaginationConfig
  • func DefaultOffsetPagingConfig() *OffsetPaginationConfig
  • func (c *OffsetPaginationConfig) SetAdditionalParams(v map[string]string) *OffsetPaginationConfig
  • func (c *OffsetPaginationConfig) SetDataFieldName(name string) *OffsetPaginationConfig
  • func (c *OffsetPaginationConfig) SetLimitFieldName(name string) *OffsetPaginationConfig
  • func (c *OffsetPaginationConfig) SetOffsetFieldName(name string) *OffsetPaginationConfig
  • func (c *OffsetPaginationConfig) SetPaginationFieldName(name string) *OffsetPaginationConfig
  • func (c *OffsetPaginationConfig) SetTotalFieldName(name string) *OffsetPaginationConfig
• type PagingConfig
  • func DefaultPagingConfig() *PagingConfig
  • func (c *PagingConfig) SetAdditionalParams(v map[string]string) *PagingConfig
  • func (c *PagingConfig) SetContentFieldName(v string) *PagingConfig
  • func (c *PagingConfig) SetFirstPageNumber(v int) *PagingConfig
  • func (c *PagingConfig) SetPageParamName(v string) *PagingConfig
  • func (c *PagingConfig) SetSizeParamName(v string) *PagingConfig
  • func (c *PagingConfig) SetTotalCountFieldName(v string) *PagingConfig

Constants

const (
	//LogLevelEnvVar is OS variable name that controlls logging level
	LogLevelEnvVar = "EQUINIX_REST_LOG"
)

Types

type ApplicationError

type ApplicationError struct {
	//Code is short error identifier
	Code string
	//Message is textual description of an error
	Message string
	//Property is a name of resource property that is related to an error
	Property string
	//AdditionalInfo provides additional information about an error
	AdditionalInfo string
}

ApplicationError describes standardized application error

func (ApplicationError) Error

func (e ApplicationError) Error() string

type Client

type Client struct {
	//PageSize determines default page size for GET requests on resource collections
	PageSize int

	*resty.Client
	// contains filtered or unexported fields
}

Client describes Equinix REST client implementation. Implementation is based on github.com/go-resty

func NewClient

func NewClient(ctx context.Context, baseURL string, httpClient *http.Client) *Client

NewClient creates new Equinix REST client with a given HTTP context, URL and http client. Equinix REST client is based on github.com/go-resty

func (*Client) Do

func (c *Client) Do(method string, path string, req *resty.Request) (*resty.Response, error)

Do runs given method on a given path with given request and returns response and error

func (*Client) Execute

func (c *Client) Execute(req *resty.Request, method string, path string) error

Execute runs provided request using provider http method and path

func (Client) GetOffsetPaginated

func (c Client) GetOffsetPaginated(path string, result interface{}, conf *OffsetPaginationConfig) ([]interface{}, error)

GetOffsetPaginated uses HTTP GET requests to retrieve list of all objects from paginated responses that use offset & limit attributes in a separate pagination object. Requests are executed against given path, pagination aspects are controlled with PagingConfig

func (Client) GetPaginated

func (c Client) GetPaginated(path string, result interface{}, conf *PagingConfig) ([]interface{}, error)

GetPaginated uses HTTP GET requests to retrieve list of all objects from paginated responses. Requests are executed against given path, pagination aspects are controlled with PagingConfig

func (*Client) SetPageSize

func (c *Client) SetPageSize(pageSize int) *Client

SetPageSize sets page size used by Equinix REST client for paginated queries

type Error

type Error struct {
	//HTTPCode is HTTP status code
	HTTPCode int
	//Message is textual, general description of an error
	Message string
	//ApplicationErrors is list of one or more application sub-errors
	ApplicationErrors []ApplicationError
}

Error describes REST API error

func (Error) Error

func (e Error) Error() string

type OffsetPaginationConfig

type OffsetPaginationConfig struct {
	PaginationFieldName string
	OffsetFieldName     string
	LimitFieldName      string
	TotalFieldName      string
	DataFieldName       string
	AdditionalParams    map[string]string
}

OffsetPaginationConfig is used to describe pagination aspects

func DefaultOffsetPagingConfig

func DefaultOffsetPagingConfig() *OffsetPaginationConfig

DefaultOffsetPagingConfig returns OffsetPaginationConfig with default values

func (*OffsetPaginationConfig) SetAdditionalParams

func (c *OffsetPaginationConfig) SetAdditionalParams(v map[string]string) *OffsetPaginationConfig

SetAdditionalParams sets additional query parameters that will be used in a request

func (*OffsetPaginationConfig) SetDataFieldName

func (c *OffsetPaginationConfig) SetDataFieldName(name string) *OffsetPaginationConfig

SetDataFieldName sets data field name

func (*OffsetPaginationConfig) SetLimitFieldName

func (c *OffsetPaginationConfig) SetLimitFieldName(name string) *OffsetPaginationConfig

SetLimitFieldName sets limit field name

func (*OffsetPaginationConfig) SetOffsetFieldName

func (c *OffsetPaginationConfig) SetOffsetFieldName(name string) *OffsetPaginationConfig

SetOffsetFieldName sets offset field name

func (*OffsetPaginationConfig) SetPaginationFieldName

func (c *OffsetPaginationConfig) SetPaginationFieldName(name string) *OffsetPaginationConfig

SetPaginationFieldName sets pagination field name

func (*OffsetPaginationConfig) SetTotalFieldName

func (c *OffsetPaginationConfig) SetTotalFieldName(name string) *OffsetPaginationConfig

SetTotalFieldName sets total field name

type PagingConfig

type PagingConfig struct {
	//TotalCountFieldName is name of a field in a response struct that indicates total number of elements in collection
	TotalCountFieldName string
	//ContentFieldName is a name of a field that holds slice of elements
	ContentFieldName string
	//SizeParamName is a name of page size query parameter
	SizeParamName string
	//PageParamName is a name of page number query parameter
	PageParamName string
	//FirstPageNumber is a first page number returned by the server (typically 0 or 1)
	FirstPageNumber int
	//AdditionalParams is a map of additional query parameters that will be set in GET request
	AdditionalParams map[string]string
}

PagingConfig is used to describe pagination aspects like naming of query parameters

func DefaultPagingConfig

func DefaultPagingConfig() *PagingConfig

DefaultPagingConfig returns PagingConfig with default values

func (*PagingConfig) SetAdditionalParams

func (c *PagingConfig) SetAdditionalParams(v map[string]string) *PagingConfig

SetAdditionalParams sets additional query parameters that will be used in a request

func (*PagingConfig) SetContentFieldName

func (c *PagingConfig) SetContentFieldName(v string) *PagingConfig

SetContentFieldName sets totalCount field name

func (*PagingConfig) SetFirstPageNumber

func (c *PagingConfig) SetFirstPageNumber(v int) *PagingConfig

SetFirstPageNumber sets number of a fist page as returned by the server

func (*PagingConfig) SetPageParamName

func (c *PagingConfig) SetPageParamName(v string) *PagingConfig

SetPageParamName sets page query parameter name

func (*PagingConfig) SetSizeParamName

func (c *PagingConfig) SetSizeParamName(v string) *PagingConfig

SetSizeParamName sets size query parameter name

func (*PagingConfig) SetTotalCountFieldName

func (c *PagingConfig) SetTotalCountFieldName(v string) *PagingConfig

SetTotalCountFieldName sets totalCount field name