@nutanix-scratch/microseg-js-client

Javascript Client For Nutanix Microseg Versioned APIs

The Javascript client for Nutanix Microseg Versioned APIs is designed for Javascript client application developers offering them simple and flexible access to APIs that manage Network Security Policy configuration of Nutanix clusters.

Features

• Invoke Nutanix APIs with a simple interface.
• Handle Authentication seamlessly.
• Reduce boilerplate code implementation.
• Use standard methods for installation.

Version

• API version: v4.0.b1
• Package version: 4.0.1-beta.1

Requirements.

Node.JS 14, 15, 16, 17 and 18 are fully supported and tested.

Installation & Usage

Installation

This library is distributed on npm. In order to add it as a dependency, run the following command:

$ npm install @nutanix-api/microseg-js-client

Configuration

The javascript client for Nutanix Microseg Versioned 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
maxRetryAttempts	Maximum number of retry attempts while connecting to the cluster	No	5
retryInterval	Interval in milliseconds at which retry attempts are made	No	3000
loggerFile	File location to which debug logs are written to	No	N/A
connectTimeout	Connection timeout in milliseconds for all operations	No	30000
readTimeout	Read timeout in milliseconds for all operations	No	30000

This module can be used in the CommonJS (CJS) , ECMAScript6(ES6) and Universal Module Definition(UMD) syntax While using the module in browser frameworks like React or Vue.JS , you can use import/export. Older Node.js versions can continue to use the require ().

For CommonJs:

const sdk = require("@nutanix-api/microseg-js-client/dist/lib/index");
let client = new sdk.ApiClient();

For ES6 modules:

import ApiClient from "@nutanix-api/microseg-js-client/dist/es/ApiClient";

Sample Configuration

import ApiClient from "@nutanix-api/microseg-js-client/dist/es/ApiClient";

let client = new ApiClient();
client.host = '10.19.50.27'; // IPv4/IPv6 address or FQDN of the cluster
client.port = 9440; // Port to which to connect to
client.username = 'admin'; // UserName to connect to the cluster
client.password = 'password'; // Password to connect to the cluster

Authentication

Nutanix APIs currently support HTTP Basic Authentication only, and the client can be configured using the username and password parameters to send Basic headers along with every request.

Retry Mechanism

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:

• 408 - Request Timeout
• 502 - Bad Gateway
• 503 - Service Unavailable

import ApiClient from "@nutanix-api/microseg-js-client/dist/es/ApiClient";

let client = new ApiClient();
client.maxRetryAttempts = 5 // Max retry attempts while reconnecting on a loss of connection
client.retryInterval = 5000 // Interval in ms to use during retry attempts

Usage

Invoking an operation

import ApiClient from "@nutanix-api/microseg-js-client/dist/es/ApiClient";
import AddressGroupsApi from "@nutanix-api/microseg-js-client/dist/es/apis/addressgroups-endpoints";
// Configure the client
// ...
let client = new ApiClient();
// Initialize the API
let addressGroupsApi = new AddressGroupsApi(client);
let extId = "string_sample_data";

addressGroupsApi.getAddressGroupById(extId).then(({data, response}) => {
    console.log(`API returned the following status code: ${response.status}`);
}).catch((err) =>  {
    console.log(`Error is: ${err}`);
});

Request Options

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.

Client headers

The 'ApiClient' can be configured to send additional headers on each request.

import ApiClient from "@nutanix-api/microseg-js-client/dist/es/ApiClient";

let client = new ApiClient();
client.addDefaultHeader('Accept-Encoding','gzip, deflate, br');

You can also modify the headers sent with each individual operation:

Operation specific headers

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 ApiClient from "@nutanix-api/microseg-js-client/dist/es/ApiClient";
import AddressGroupsApi from "@nutanix-api/microseg-js-client/dist/es/apis/addressgroups-endpoints";
// Configure the client
// ...
let client = new ApiClient();
// Initialize the API
let addressGroupsApi = new AddressGroupsApi(client);
let extId = "string_sample_data";

// Perform Get call
addressGroupsApi.getAddressGroupById(extId).then(({data, response}) => {
console.log(`API returned the following status code: ${response.status}`);
// Extract E-Tag Header
let etagValue = ApiClient.getEtag(data)
// ...
let addressGroup = data.data;
// initialize/change parameters for update

// Perform Update
addressGroupsApi.updateAddressGroupById(addressGroup, extId, {"If-Match" : etagValue}).then(({data, response}) => {
    console.log(`API returned the following status code: ${response.status}`);
}).catch((err) => {
    console.log(`Error is: ${err}`);
});

List Operations

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.

List Options can be passed to list operations in order to perform pagination, filtering etc.

import ApiClient from "@nutanix-api/microseg-js-client/dist/es/ApiClient";
import AddressGroupsApi from "@nutanix-api/microseg-js-client/dist/es/apis/addressgroups-endpoints";
// Configure the client
// ...
let client = new ApiClient();
// Initialize the API
let addressGroupsApi = new AddressGroupsApi(client);

//Construct List Options
var listOptions = new Object();
listOptions.$page = 0;
listOptions.$limit = 50;
listOptions.$filter = "string_sample_data";
listOptions.$orderby = "string_sample_data";
listOptions.$select = "string_sample_data";

addressGroupsApi.listAddressGroups(listOptions).then(({data, response}) => {
    console.log(`API returned the following status code: ${response.status}`);
}).catch((err) =>  {
    console.log(`Error is: ${err}`);
});

The list of filterable and sortable fields with expansion keys can be found in the documentation here.

API Reference

This library has a full set of API Reference Documentation. This documentation is auto-generated, and the location may change.

License

This library is licensed under Nutanix proprietary license. Full license text is available in LICENSE.

Contact us

In case of issues please reach out to us at the mailing list