Skip to content

release nci-7.5 #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
orichter wants to merge 1 commit into
base: main
Choose a base branch
from
Open

release nci-7.5 #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 54 additions & 87 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,98 +1,65 @@
# Java Client Libraries for Nutanix APIs
# Java SDKs for Nutanix APIs
Staging Area for Java SDKs of Nutanix APIs to be published externally

# Versions
| Namespace | Description | Package Name | Version |
|--------------|----------------------------------------------|-----------------------------------------|------------------|
| vmm | Virtual Machine Management | com.nutanix.api.vmm-java-client | 4.0.3-alpha-1 |
| prism | Tasks and Monitoring | com.nutanix.api.prism-java-client | 4.0.3-alpha-2 |
| clustermgmt | Infra Management | com.nutanix.api.clustermgmt-java-client | 4.0.1-beta-1 |
| aiops | Stats | com.nutanix.api.aiops-java-client | 4.0.3-alpha-2 |
| storage | Storage Containers | com.nutanix.api.storage-java-client | 4.0.2-alpha-3 |
| iam | Identity and Access Management | com.nutanix.api.iam-java-client | 4.0.1-beta-1 |
| lcm | Life Cycle Management | com.nutanix.api.lcm-java-client | 4.0.1-alpha-1 |
| files | File Server Management | com.nutanix.api.files-java-client | 4.0.1-alpha-2 |
| networking | AHV Networking | com.nutanix.api.networking-java-client | 4.0.1-beta-1 |
| dataprotection | Data Protection | com.nutanix.api.dataprotection-java-client | 4.0.1-alpha-4 |

This project contains steps for installing and using Java Client Libraries for Nutanix APIs grouped together by their namespace. Clients are currently
available for the following namespaces.

| Namespace | Description |
|--------------|-----------------------------------------------------------------------------------------------------|
| vmm | Manage the life-cycle of virtual machines hosted on Nutanix clusters. |
| prism | Manage Tasks, Category Associations, Alerts, Alert policies, Events and Audits.|
| clustermgmt | Manage Hosts, Clusters, and other Nutanix infrastructure. |
| aiops | Manage Nutanix infrastructure using Analysis, Reporting, Capacity Planning, What if Analysis, VM Rightsizing, Troubleshooting, App Discovery, Broad Observability, and Ops Automation through Playbooks.|
| storage | Manage Volume Groups and Storage Containers hosted on Nutanix clusters. |
| iam | Manage User Identity and Access. |
| lcm | Manage Infrastructure, Software and Firmware Upgrades. |
| files | Manage virtual file servers, create and configure shares for client access, protect them using DR and sync policies, provision storage space and administer security controls.|
| networking | Manage networking configuration on Nutanix clusters, including AHV and advanced networking.|
# Project Structure
Project contains a top level directory corresponding to each namespace as listed above. Each namespace directory contains
a README with instructions for getting started with that client.


## Getting Started

The libraries are distributed on [Maven Central](https://mvnrepository.com/repos/central). In order to add it as a dependency, please do the following:

#### Using Maven

In order to use the aiops java client
Project will contain the following:
- a directory corresponding to each namespace as listed above. Each namespace directory will contain a README.md
pertaining to the namespace

# Packages
Java packages will be published into this repository for each namespace as listed above. The package will contain the
following
| Package File | Description |
|------------------------------------------------|-------------------------------|
| {namespace}-java-client-{version}.jar | Jar file |
| {namespace}-java-client-{version}.sha1 | sha1 of the jar file |
| {namespace}-java-client-{version}.md5 | md5 of the jar file |
| {namespace}-java-client-{version}-sources.jar | Sources Jar file |
| {namespace}-java-client-{version}-sources.sha1 | sha1 of the sources jar file |
| {namespace}-java-client-{version}-sources.md5 | md5 of the sources jar file |
| {namespace}-java-client-{version}-javadoc.jar | Javadoc Jar file |
| {namespace}-java-client-{version}-javadoc.sha1 | sha1 of the javadoc jar file |
| {namespace}-java-client-{version}-javadoc.md5 | md5 of the javadoc jar file |
| {namespace}-java-client-{version}.pom | pom file of the project |


# Publishing process

Edit the pom.xml to change the url attribute from

```xml
<dependency>
<groupId>com.nutanix.api</groupId>
<artifactId>aiops-java-client</artifactId>
<version>4.0.2-alpha-1</version>
</dependency>
```
and to use the vmm client

```xml
<dependency>
<groupId>com.nutanix.api</groupId>
<artifactId>vmm-java-client</artifactId>
<version>4.0.2-alpha-1</version>
</dependency>
```
and so on...
#### Using Gradle
In order to use the aiops java client

```groovy
dependencies {
implementation("com.nutanix.api:aiops-java-client:4.0.1-alpha-1")
}
<url>https://github.com/nutanix-core/ntnx-api-java-sdk-external/blob/main/vmm/README.md</url>
to
<url>https://github.com/nutanix/ntnx-api-java-clients/blob/main/vmm/README.md</url>
```

and to use the vmm client

```groovy
dependencies {
implementation("com.nutanix.api:vmm-java-client:4.0.1-alpha-1")
}
```

and so on...


and consume them as:
## Architecture

```java
import com.nutanix.aio.java.client.ApiClient;
![image (1)](https://user-images.githubusercontent.com/50940815/174028904-fb7c5869-c033-4d19-a101-25388f9d09aa.png)

public class Sample {
public void configureClient() {
ApiClient client = new ApiClient();
client.setHost("10.19.50.27"); // IPv4/IPv6 address or FQDN of the cluster
client.setPort(9440); // Port to which to connect to
client.setUsername("admin"); // UserName to connect to the cluster
client.setPassword("password"); // Password to connect to the cluster
}
}
## Important Note:
```diff
- SDK packages are uploaded through an automated pipeline. No manual changes must be made.
```
Click [here](https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages) for more info about github packages.

For detailed instructions on installing individual clients, please refer to the README documentation for the respective clients in the namespace directories.


## Status
These are auto generated Java clients generated from Open API v3.0 yaml specification documents.
Due to the auto-generated nature of these clients, they may contain breaking changes from one release to
the next.

## API Reference
These clients have a full set of [API Reference Documentation](https://developers.nutanix.com/). 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](https://developers.nutanix.com/license).

## Contact us
In case of issues please reach out to us at the [mailing list](mailto:[email protected]).
#### Contact List
1. [Sujeet Mishra(Staging Publishing)](mailto:[email protected])
2. [Athar Ejaz(Staging Publishing)](mailto:[email protected])
3. [Gagan Singh(Staging Publishing)](mailto:[email protected])
4. [Owen Richter(External Publishing)](mailto:[email protected])
82 changes: 62 additions & 20 deletions aiops/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,35 @@
# Java Client For Nutanix Aiops Versioned APIs
# Java Client For Nutanix AIOps APIs

The Java client for Nutanix Aiops Versioned APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage infrastructure on-premises and in the cloud seamlessly through AIOps features such as Analysis, Reporting, Capacity Planning, What if Analysis, VM Rightsizing, Troubleshooting, App Discovery, Broad Observability, and Ops Automation through Playbooks.
The Java client for Nutanix AIOps APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage infrastructure on-premises and in the cloud seamlessly through AIOps features such as Analysis, Reporting, Capacity Planning, What if Analysis, VM Rightsizing, Troubleshooting, App Discovery, Broad Observability, and Ops Automation through Playbooks.
## 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.a1
- Package version: 4.0.2-alpha-1
- API version: v4.2.b1
- Package version: 4.2.1-beta-1

## Version Negotiation

By default, the client negotiates the API version with the server to ensure compatibility. Version negotiation is **enabled by default**. To disable version negotiation and use a fixed API version, call the `disableVersionNegotiation()` method on the ApiClient:

```java
import com.nutanix.aio.java.client.ApiClient;

public class Sample {
public void configureClient() {
ApiClient client = new ApiClient();
client.setHost("10.19.50.27");
client.setUsername("admin");
client.setPassword("password");
client.disableVersionNegotiation(); // Disables automatic version negotiation
}
}
```

When version negotiation is disabled, the client will use the SDK's default API version.

## Requirements.

Expand All @@ -28,21 +48,21 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or
<dependency>
<groupId>com.nutanix.api</groupId>
<artifactId>aiops-java-client</artifactId>
<version>4.0.2-alpha-1</version>
<version>4.2.1-beta-1</version>
</dependency>
```

#### Using Gradle

```groovy
dependencies {
implementation("com.nutanix.api:aiops-java-client:4.0.2-alpha-1")
implementation("com.nutanix.api:aiops-java-client:4.2.1-beta-1")
}
```

## Configuration

The Java client for Nutanix Aiops Versioned APIs can be configured with the following parameters
The Java client for Nutanix AIOps APIs can be configured with the following parameters

| Parameter | Description | Required | Default Value|
|-----------|----------------------------------------------------------------------------------|----------|--------------|
Expand All @@ -57,6 +77,7 @@ The Java client for Nutanix Aiops Versioned APIs can be configured with the foll
| retryInterval| Interval in milliseconds at which retry attempts are made | No | 3000 |
| connectTimeout| Connection timeout in milliseconds for all operations | No | 30000 |
| readTimeout| Read timeout in milliseconds for all operations | No | 30000 |
| downloadDirectory| Directory where downloaded files will be stored | No | current Working Directory|


### Sample Configuration
Expand All @@ -76,21 +97,43 @@ public class Sample {
```

### 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.
Nutanix APIs currently support two type of authentication schemes:

- **HTTP Basic Authentication**
- The Java client can be configured using the username and password parameters to send Basic headers along with every request.
- **API Key Authentication**
- The Java client can be configured to set an API key to send "**X-ntnx-api-key**" header with every request.
```java
import com.nutanix.aio.java.client.ApiClient;

public class Sample {
public void configureClient() {
ApiClient client = new ApiClient();
client.setApiKey("abcde12345");
}
}
```


### 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408)
- [429 - Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429)
- [502 - Bad Gateway](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502)
- [503 - Service Unavailable](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503)

The client will also redirect requests that fail with [302 - Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) to the new location specified in the response header `Location`.
! Note : Within Java SDK maximum retry attempts and maximum redirect attempts are limited by the same variable maxRetryAttempts.

```java
import com.nutanix.aio.java.client.ApiClient;

public class Sample {
public void configureClient() {
ApiClient client = new ApiClient();
client.setMaxRetryAttempts(5); // Max retry attempts while reconnecting on a loss of connection
client.setRetryInterval(5000); // Interval in ms to use during retry attempts
client.setRetryInterval(5000); // Interval in ms to use during retry or redirection attempts
}
}
```
Expand Down Expand Up @@ -139,7 +182,6 @@ Nutanix APIs require that concurrent updates are protected using [ETag](https://
```java
import com.nutanix.aio.java.client.ApiClient;


// this sample code is not usable directly for real use-case

public class Sample {
Expand Down Expand Up @@ -171,26 +213,26 @@ List Operations for Nutanix APIs support pagination, filtering, sorting and proj
| $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](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionfilter) 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 expand 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. Allowed system query options are $filter,$select, $orderby. |
| $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.
```java
import com.nutanix.aio.java.client.ApiClient;
import com.nutanix.aio.java.client.api.ClusterApi;
import com.nutanix.dp1.aio.aiops.v4.clusterMetrics.ClusterListApiResponse;
import com.nutanix.aio.java.client.api.StatsApi;
import com.nutanix.dp1.aio.aiops.v4.config.EntityDescriptorListApiResponse;

public class Sample {
public void performOperation() {
ApiClient client = new ApiClient();
// Configure the client
// ...
ClusterApi clusterApi = new ClusterApi(client);
StatsApi statsApi = new StatsApi(client);
String sourceExtId = "A3EbFecf-ccbE-42bF-FDcF-bD96D8EEaBCA";
int page = 0;
int limit = 50;
String null = "string_sample_data";
String null = "string_sample_data";
ClusterListApiResponse clusterListApiResponse = clusterApi.listResourcesForAllClusters(page, limit, null, null);
String filter = null;
EntityDescriptorListApiResponse entityDescriptorListApiResponse = statsApi.getEntityDescriptorsV4(sourceExtId, page, limit, filter);
}
}
```
Expand All @@ -199,10 +241,10 @@ The list of filterable and sortable fields with expansion keys can be found in t

## API Reference

This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=aiops&version=v4.0.a1&language=java). This documentation is auto-generated, and the location may change.
This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=aiops&version=v4.2.b1&language=java). 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](https://developers.nutanix.com/license).
This library is licensed under Apache 2.0 license. Full license text is available in [LICENSE](https://www.apache.org/licenses/LICENSE-2.0.txt).

## Contact us
In case of issues please reach out to us at the [mailing list](mailto:[email protected])
Loading