The Go client for Nutanix Prism APIs is designed for Go client application developers offering them simple and flexible access to APIs that manage Tasks, Category Associations and Submit Batch Operations.
- Invoke Nutanix APIs with a simple interface.
- Handle Authentication seamlessly.
- Reduce boilerplate code implementation.
- Use standard methods for installation.
- API version: v4.0
- Package version: v4.0.1
Go 1.17 or above are fully supported and tested.
$ go get github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/...$ go get github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/[email protected]In go.mod file add the following
module your-module
go {GO_VERSION}
require (
github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4 latest
)
In go.mod file add the following
module your-module
go {GO_VERSION}
require (
github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4 v4.0.1
)
The Go client for Nutanix Prism APIs can be configured with the following parameters
| Parameter | Description | Required | Default Value |
|---|---|---|---|
| Scheme | URI scheme for connecting to the cluster (HTTP or HTTPS using SSL/TLS) | No | https |
| Host | IPv4/IPv6 address or FQDN of the cluster to which the client will connect to | Yes | N/A |
| Port | Port on the cluster to which the client will connect to | No | 9440 |
| Username | Username to connect to a cluster | Yes | N/A |
| Password | Password to connect to a cluster | Yes | N/A |
| Debug | Runs the client in debug mode if specified | No | False |
| VerifySSL | Verify SSL certificate of cluster, the client will connect to | No | True |
| Proxy | Configure a proxy, the client will connect to | No | N/A |
| MaxRetryAttempts | Maximum number of retry attempts while connecting to the cluster | No | 5 |
| RetryInterval | Interval (in time.Duration) at which retry attempts are made | No | 3 * time.Second |
| LoggerFile | File location to which debug logs are written to | No | N/A |
| ConnectTimeout | Connection timeout (in time.Duration) for all operations | No | 30 * time.Second |
| ReadTimeout | Read timeout (in time.Duration) for all operations | No | 30 * time.Second |
| DownloadDirectory | Directory location for files to download | No | Current Directory |
| DownloadChunkSize | Chunk size in bytes for files to download | No | 8*1024 bytes |
| RootCACertificateFile | PEM encoded Root CA certificate file path | No | N/A |
| ClientCertificateFile | PEM encoded client certificate file path | No | N/A |
| ClientKeyFile | PEM encoded client key file path | No | N/A |
A Proxy can be configured with the following parameters
| Parameter | Description | Required | Default Value |
|---|---|---|---|
| Proxy.Scheme | URI Scheme for connecting to the proxy ("http", "https" or "socks5") | Yes | N/A |
| Proxy.Host | Host of the proxy to which the client will connect to | Yes | N/A |
| Proxy.Port | Port of the proxy to which the client will connect to | Yes | N/A |
| Proxy.Username | Username to connect to the proxy | - | N/A |
| Proxy.Password | Password to connect to the proxy | - | N/A |
import (
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/client"
)
var (
ApiClientInstance *client.ApiClient
)
ApiClientInstance = client.NewApiClient()
ApiClientInstance.Host = "10.19.50.27" // IPv4/IPv6 address or FQDN of the cluster
ApiClientInstance.Port = 9440 // Port to which to connect to
ApiClientInstance.Username = "admin" // UserName to connect to the cluster
ApiClientInstance.Password = "password" // Password to connect to the clusterimport (
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/client"
)
var (
ApiClientInstance *client.ApiClient
)
ApiClientInstance = client.NewApiClient()
// Configure the client as shown in the previous step
// ...
ApiClientInstance.Proxy = new(client.Proxy)
ApiClientInstance.Proxy.Scheme = "socks5"
ApiClientInstance.Proxy.Username = "proxy_admin"
ApiClientInstance.Proxy.Password = "proxy_password"
ApiClientInstance.Proxy.Host = "127.0.0.1"
ApiClientInstance.Proxy.Port = 1080import (
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/client"
)
var (
ApiClientInstance *client.ApiClient
)
ApiClientInstance = client.NewApiClient()
// Configure the client as shown in the previous step
// ...
ApiClientInstance.RootCACertificateFile = "/home/certs/ca.pem"
ApiClientInstance.ClientCertificateFile = "/home/certs/YourService/YourService.crt"
ApiClientInstance.ClientKeyFile = "/home/certs/YourService/YourService.key"Nutanix APIs currently support two type of authentication schemes:
- HTTP Basic Authentication - The Go client can be configured using the username and password parameters to send Basic headers along with every request.
- API Key Authentication - The Go client can be configured to set an API key to send "X-ntnx-api-key" header with every request.
import (
"github.com/nutanix-core/ntnx-api-go-sdk-internal/iam-api-external-go-client/v16/client"
)
var (
ApiClientInstance *client.ApiClient
)
ApiClientInstance = client.NewApiClient()
ApiClientInstance.SetApiKey("abcde12345")The client can be configured to retry requests that fail with the following status codes. The numbers of seconds before which the next retry is attempted is determined by the retryInterval:
The client will also redirect requests that fail with 302 - Found to the new location specified in the response header Location.
! Note : Within Golang SDK maximum redirect attempts are limited to 10 by default and cannot be changed tro a custom value.
import (
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/client"
"time"
)
var (
ApiClientInstance *client.ApiClient
)
ApiClientInstance = client.NewApiClient()
ApiClientInstance.MaxRetryAttempts = 5 // Max retry attempts while reconnecting on a loss of connection
ApiClientInstance.RetryInterval = 5 * time.Second // Interval (in time.Duration) to use during retry attempts - integer values are treated as time.Nanosecond by defaultimport (
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/client"
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/api"
)
var (
ApiClientInstance *client.ApiClient
CategoriesApiInstance *api.CategoriesApi
)
ApiClientInstance = client.NewApiClient()
// Configure the client as shown in the previous step
// ...
// Initialize the API
CategoriesApiInstance = api.NewCategoriesApi(ApiClientInstance)
extId := "ddb52B69-Ec3E-562a-1ea4-82D2D6A5b106"
expand_ := "string_sample_data"
//
getResponse, err := CategoriesApiInstance.GetCategoryById(&extId, &expand_)
if err != nil {
....
}The library provides the ability to specify additional options that can be applied directly on the 'ApiClient' object used to make network calls to the API. The library also provides a mechanism to specify operation specific headers.
The 'ApiClient' can be configured to send additional headers on each request.
import (
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/client"
)
var (
ApiClientInstance *client.ApiClient
)
ApiClientInstance = client.NewApiClient()
ApiClientInstance.AddDefaultHeader("Accept-Encoding", "gzip, deflate, br")You can also modify the headers sent with each individual operation:
Nutanix APIs require that concurrent updates are protected using ETag headers. This would mean that the ETag header received in the response of a fetch (GET) operation should be used as an If-Match header for the modification (PUT) operation.
import (
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/client"
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/api"
// import request body DTO for put api
)
var (
ApiClientInstance *client.ApiClient
CategoriesApiInstance *api.CategoriesApi
)
ApiClientInstance = client.NewApiClient()
// Configure the client as shown in a previous step
// ...
// Initialize the API
CategoriesApiInstance = api.NewCategoriesApi(ApiClientInstance)
extId := "ddb52B69-Ec3E-562a-1ea4-82D2D6A5b106"
expand_ := "string_sample_data"
//
getResponse, err := CategoriesApiInstance.GetCategoryById(&extId, &expand_)
if err != nil {
....
}
// Extract E-Tag Header
etagValue := ApiClientInstance.GetEtag(getResponse)
args := make(map[string] interface {})
args["If-Match"] = etagValue
// ...
// Perform update call with received E-Tag reference
// initialize/change parameters for update
// ...
requestBody := getResponse.GetData().(import1.byte[])
// The body parameter in the following operation is received from the previous GET request's response which needs to be updated.
response, err := CategoriesApiInstance.UpdateCategoryById(&requestBody&extId, , args)
if err != nil {
....
}List Operations for Nutanix APIs support pagination, filtering, sorting and projections. The table below details the parameters that can be used to set the options for pagination etc.
| Parameter | Description |
|---|---|
| _page | specifies the page number of the result set. Must be a positive integer between 0 and the maximum number of pages that are available for that resource. Any number out of this range will lead to no results being returned. |
| _limit | specifies the total number of records returned in the result set. Must be a positive integer between 0 and 100. Any number out of this range will lead to a validation error. If the limit is not provided a default value of 50 records will be returned in the result set |
| _filter | allows clients to filter a collection of resources. The expression specified with $filter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response. Expression specified with the $filter must conform to the OData V4.01 URL conventions. |
| _orderby | allows clients to specify the sort criteria for the returned list of objects. Resources can be sorted in ascending order using asc or descending order using desc. If asc or desc are not specified the resources will be sorted in ascending order by default. For example, 'orderby=templateName desc' would get all templates sorted by templateName in desc order. |
| _select | allows clients to request a specific set of properties for each entity or complex type. Expression specified with the $select must conform to the OData V4.01 URL conventions. If a $select expression consists of a single select item that is an asterisk (i.e., *), then all properties on the matching resource will be returned. |
| _expand | allows clients to request related resources when a resource that satisfies a particular request is retrieved. Each expanded item is evaluated relative to the entity containing the property being expanded. Other query options can be applied to an expanded property by appending a semicolon-separated list of query options, enclosed in parentheses, to the property name. Permissible system query options are $filter,$select and $orderby. |
import (
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/client"
"github.com/nutanix/ntnx-api-golang-clients/prism-go-client/v4/api"
)
var (
ApiClientInstance *client.ApiClient
BatchesApiInstance *api.BatchesApi
)
ApiClientInstance = client.NewApiClient()
// Configure the client
// ...
// Initialize the API
BatchesApiInstance = api.NewBatchesApi(ApiClientInstance)
page_ := 0
limit_ := 50
filter_ := "string_sample_data"
orderby_ := "string_sample_data"
select_ := "string_sample_data"
//
response, err := BatchesApiInstance.ListBatches(&page_, &limit_, &filter_, &orderby_, &select_)
if err != nil {
....
}
The list of filterable and sortable fields with expansion keys can be found in the documentation here.
This library has a full set of API Reference Documentation. This documentation is auto-generated, and the location may change.
This library is licensed under Apache 2.0 license. Full license text is available in LICENSE.
In case of issues please reach out to us at the mailing list