diff --git a/README.md b/README.md index 82ecb4a..0d01051 100644 --- a/README.md +++ b/README.md @@ -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 - - com.nutanix.api - aiops-java-client - 4.0.2-alpha-1 - -``` -and to use the vmm client - -```xml - - com.nutanix.api - vmm-java-client - 4.0.2-alpha-1 - -``` -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") -} +https://github.com/nutanix-core/ntnx-api-java-sdk-external/blob/main/vmm/README.md +to +https://github.com/nutanix/ntnx-api-java-clients/blob/main/vmm/README.md ``` -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:sdk@nutanix.com). +#### Contact List +1. [Sujeet Mishra(Staging Publishing)](mailto:sujeet.mishra@nutanix.com) +2. [Athar Ejaz(Staging Publishing)](mailto:athar.ejaz@nutanix.com) +3. [Gagan Singh(Staging Publishing)](mailto:gagan.singh@nutanix.com) +4. [Owen Richter(External Publishing)](mailto:owen.richter@nutanix.com) diff --git a/aiops/README.md b/aiops/README.md index 58d3b22..462d034 100644 --- a/aiops/README.md +++ b/aiops/README.md @@ -1,6 +1,6 @@ -# 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. @@ -8,8 +8,28 @@ The Java client for Nutanix Aiops Versioned APIs is designed for Java client app - 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. @@ -28,7 +48,7 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or com.nutanix.api aiops-java-client - 4.0.2-alpha-1 + 4.2.1-beta-1 ``` @@ -36,13 +56,13 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or ```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| |-----------|----------------------------------------------------------------------------------|----------|--------------| @@ -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 @@ -76,13 +97,35 @@ 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; @@ -90,7 +133,7 @@ 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 } } ``` @@ -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 { @@ -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); } } ``` @@ -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:sdk@nutanix.com) \ No newline at end of file diff --git a/clustermgmt/README.md b/clustermgmt/README.md index 43aae22..c54bca4 100644 --- a/clustermgmt/README.md +++ b/clustermgmt/README.md @@ -1,6 +1,6 @@ -# Java Client For Nutanix Clustermgmt Versioned APIs +# Java Client For Nutanix Cluster Management APIs -The Java client for Nutanix Clustermgmt Versioned APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage Hosts, Clusters and other Infrastructure. +The Java client for Nutanix Cluster Management APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage Hosts, Clusters and other Infrastructure. ## Features - Invoke Nutanix APIs with a simple interface. - Handle Authentication seamlessly. @@ -8,8 +8,28 @@ The Java client for Nutanix Clustermgmt Versioned APIs is designed for Java clie - Use standard methods for installation. ## Version -- API version: v4.0.a2 -- Package version: 4.0.2-alpha-2 +- API version: v4.2 +- Package version: 4.2.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.clu.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. @@ -28,7 +48,7 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or com.nutanix.api clustermgmt-java-client - 4.0.2-alpha-2 + 4.2.1 ``` @@ -36,13 +56,13 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or ```groovy dependencies { - implementation("com.nutanix.api:clustermgmt-java-client:4.0.2-alpha-2") + implementation("com.nutanix.api:clustermgmt-java-client:4.2.1") } ``` ## Configuration -The Java client for Nutanix Clustermgmt Versioned APIs can be configured with the following parameters +The Java client for Nutanix Cluster Management APIs can be configured with the following parameters | Parameter | Description | Required | Default Value| |-----------|----------------------------------------------------------------------------------|----------|--------------| @@ -57,6 +77,7 @@ The Java client for Nutanix Clustermgmt Versioned APIs can be configured with th | 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 @@ -76,13 +97,35 @@ 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.clu.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.clu.java.client.ApiClient; @@ -90,7 +133,7 @@ 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 } } ``` @@ -101,17 +144,18 @@ public class Sample { ```java import com.nutanix.clu.java.client.ApiClient; -import com.nutanix.clu.java.client.api.ClusterApi; -import com.nutanix.dp1.clu.clustermgmt.v4.config.GetClusterResponse; +import com.nutanix.clu.java.client.api.ClustersApi; +import com.nutanix.dp1.clu.clustermgmt.v4.config.GetClusterApiResponse; public class Sample { public void performOperation() { ApiClient client = new ApiClient(); // Configure the client // ... - ClusterApi clusterApi = new ClusterApi(client); - String clusterExtId = "1B3629ec-e507-524a-BEdB-F9eF55b671af"; - GetClusterResponse getClusterResponse = clusterApi.getCluster(clusterExtId); + ClustersApi clustersApi = new ClustersApi(client); + String extId = "F149cC6e-A57c-0F9a-A88e-e0Cec3f1a43d"; + String expand = null; + GetClusterApiResponse getClusterApiResponse = clustersApi.getClusterById(extId, expand); } } ``` @@ -137,7 +181,7 @@ You can also modify the headers sent with each individual operation: Nutanix APIs require that concurrent updates are protected using [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. ```java import com.nutanix.clu.java.client.ApiClient; -import com.nutanix.dp1.clu.clustermgmt.v4.config.GetClusterResponse; +import com.nutanix.dp1.clu.clustermgmt.v4.config.GetClusterApiResponse; public class Sample { public void performOperation() { @@ -145,18 +189,19 @@ public class Sample { // Configure the client // ... // perform GET call - ClusterApi clusterApi = new ClusterApi(client); - String clusterExtId = "1B3629ec-e507-524a-BEdB-F9eF55b671af"; - GetClusterResponse getClusterResponse = clusterApi.getCluster(clusterExtId); + ClustersApi clustersApi = new ClustersApi(client); + String extId = "F149cC6e-A57c-0F9a-A88e-e0Cec3f1a43d"; + String expand = null; + GetClusterApiResponse getClusterApiResponse = clustersApi.getClusterById(extId, expand); // Extract E-Tag Header - final String eTagHeader = ApiClient.getEtag(getClusterResponse); + final String eTagHeader = ApiClient.getEtag(getClusterApiResponse); // ... // Perform update call with received E-Tag reference - ClusterEntity clusterEntity = (ClusterEntity) getClusterResponse.getData(); + Cluster cluster = (Cluster) getClusterApiResponse.getData(); // initialize/change parameters for update HashMap opts = new HashMap<>(); opts.put("If-Match", eTagHeader); - clusterApi.updateCluster(clusterEntity, clusterExtId, opts); + clustersApi.updateClusterById(clusterextId, , opts); } } @@ -171,26 +216,28 @@ 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.clu.java.client.ApiClient; -import com.nutanix.clu.java.client.api.ClusterApi; -import com.nutanix.dp1.clu.clustermgmt.v4.config.GetClustersResponse; +import com.nutanix.clu.java.client.api.DisksApi; +import com.nutanix.dp1.clu.clustermgmt.v4.config.ListDisksApiResponse; public class Sample { public void performOperation() { ApiClient client = new ApiClient(); // Configure the client // ... - ClusterApi clusterApi = new ClusterApi(client); + DisksApi disksApi = new DisksApi(client); int page = 0; int limit = 50; - String null = "string_sample_data"; - String null = "string_sample_data"; - GetClustersResponse getClustersResponse = clusterApi.getClusters(page, limit, null, null); + String filter = null; + String orderby = null; + String apply = null; + String select = null; + ListDisksApiResponse listDisksApiResponse = disksApi.listDisks(page, limit, filter, orderby, apply, select); } } ``` @@ -199,10 +246,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=clustermgmt&version=v4.0.a2&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=clustermgmt&version=v4.2&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:sdk@nutanix.com) \ No newline at end of file diff --git a/datapolicies/README.md b/datapolicies/README.md new file mode 100644 index 0000000..b63a6dc --- /dev/null +++ b/datapolicies/README.md @@ -0,0 +1,255 @@ +# Java Client For Nutanix Data Policies APIs + +The Java client for Nutanix Data Policies APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage Policies for Disaster Recovery and Storage. +## Features +- Invoke Nutanix APIs with a simple interface. +- Handle Authentication seamlessly. +- Reduce boilerplate code implementation. +- Use standard methods for installation. +## Version + +- API version: v4.2 +- Package version: 4.2.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.dat.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + datapolicies-java-client + 4.2.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:datapolicies-java-client:4.2.1") +} +``` + +## Configuration + +The Java client for Nutanix Data Policies 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.dat.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.dat.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.dat.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.dat.java.client.ApiClient; +import com.nutanix.dat.java.client.api.RecoveryPlansApi; +import com.nutanix.dp1.dat.datapolicies.v4.config.GetDataServicesIpMappingApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + RecoveryPlansApi recoveryPlansApi = new RecoveryPlansApi(client); + String recoveryPlanExtId = "308aDB9B-bbe2-bedD-caf8-DfBCC3e20Bef"; + String extId = "2619af98-ee1b-DaA6-37bE-4c772b8F226D"; + GetDataServicesIpMappingApiResponse getDataServicesIpMappingApiResponse = recoveryPlansApi.getDataServicesIpMappingById(recoveryPlanExtId, extId); + } +} +``` + +### 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. + +```java +import com.nutanix.dat.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.dat.java.client.ApiClient; +import com.nutanix.dp1.dat.datapolicies.v4.config.GetDataServicesIpMappingApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + RecoveryPlansApi recoveryPlansApi = new RecoveryPlansApi(client); + String recoveryPlanExtId = "308aDB9B-bbe2-bedD-caf8-DfBCC3e20Bef"; + String extId = "2619af98-ee1b-DaA6-37bE-4c772b8F226D"; + GetDataServicesIpMappingApiResponse getDataServicesIpMappingApiResponse = recoveryPlansApi.getDataServicesIpMappingById(recoveryPlanExtId, extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(getDataServicesIpMappingApiResponse); + // ... + // Perform update call with received E-Tag reference + DataServicesIpMapping dataServicesIpMapping = (DataServicesIpMapping) getDataServicesIpMappingApiResponse.getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + recoveryPlansApi.updateDataServicesIpMappingById(dataServicesIpMappingrecoveryPlanExtId, extId, , opts); + } +} + +``` + +### 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](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 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.dat.java.client.ApiClient; +import com.nutanix.dat.java.client.api.RecoveryPlansApi; +import com.nutanix.dp1.dat.datapolicies.v4.config.ListDataServicesIpMappingsApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + RecoveryPlansApi recoveryPlansApi = new RecoveryPlansApi(client); + String recoveryPlanExtId = "7B8Aa04D-451E-4D5B-BeE2-90dddd859F4a"; + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String select = null; + ListDataServicesIpMappingsApiResponse listDataServicesIpMappingsApiResponse = recoveryPlansApi.listDataServicesIpMappings(recoveryPlanExtId, page, limit, filter, orderby, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=datapolicies&version=v4.2&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/dataprotection/README.md b/dataprotection/README.md new file mode 100644 index 0000000..826665f --- /dev/null +++ b/dataprotection/README.md @@ -0,0 +1,252 @@ +# Java Client For Nutanix Data Protection APIs + +The Java client for Nutanix Data Protection APIs is designed for Java client application developers offering them simple and flexible access to APIs that business Continuity with full spectrum of Disaster Recovery and Backup solution. Spanning across Single PC, Cross AZ, MultiSite. Configuration of Recovery points, Protection policies, Recovery Plans. Execution and monitoring of back up and recovery orchestrations on OnPrem as well as Cloud. +## Features +- Invoke Nutanix APIs with a simple interface. +- Handle Authentication seamlessly. +- Reduce boilerplate code implementation. +- Use standard methods for installation. +## Version + +- API version: v4.2 +- Package version: 4.2.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.dat.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + dataprotection-java-client + 4.2.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:dataprotection-java-client:4.2.1") +} +``` + +## Configuration + +The Java client for Nutanix Data Protection 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.dat.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.dat.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.dat.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.dat.java.client.ApiClient; +import com.nutanix.dat.java.client.api.ConsistencyGroupsApi; +import com.nutanix.dp1.dat.dataprotection.v4.config.GetConsistencyGroupApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + ConsistencyGroupsApi consistencyGroupsApi = new ConsistencyGroupsApi(client); + String extId = "A5FdB4AB-eBeA-adC1-86fA-7bab2AAAc5B4"; + GetConsistencyGroupApiResponse getConsistencyGroupApiResponse = consistencyGroupsApi.getConsistencyGroupById(extId); + } +} +``` + +### 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. + +```java +import com.nutanix.dat.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.dat.java.client.ApiClient; +import com.nutanix.dp1.dat.dataprotection.v4.config.GetConsistencyGroupApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + ConsistencyGroupsApi consistencyGroupsApi = new ConsistencyGroupsApi(client); + String extId = "A5FdB4AB-eBeA-adC1-86fA-7bab2AAAc5B4"; + GetConsistencyGroupApiResponse getConsistencyGroupApiResponse = consistencyGroupsApi.getConsistencyGroupById(extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(getConsistencyGroupApiResponse); + // ... + // Perform update call with received E-Tag reference + ConsistencyGroup consistencyGroup = (ConsistencyGroup) getConsistencyGroupApiResponse.getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + consistencyGroupsApi.updateConsistencyGroupById(consistencyGroupextId, , opts); + } +} + +``` + +### 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](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 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.dat.java.client.ApiClient; +import com.nutanix.dat.java.client.api.DataProtectionClusterCapabilitiesApi; +import com.nutanix.dp1.dat.dataprotection.v4.config.ListDPClusterCapabilitiesApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + DataProtectionClusterCapabilitiesApi dataProtectionClusterCapabilitiesApi = new DataProtectionClusterCapabilitiesApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String select = null; + ListDPClusterCapabilitiesApiResponse listDPClusterCapabilitiesApiResponse = dataProtectionClusterCapabilitiesApi.listDataProtectionClusterCapabilities(page, limit, filter, orderby, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=dataprotection&version=v4.2&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/files/README.md b/files/README.md new file mode 100644 index 0000000..6878348 --- /dev/null +++ b/files/README.md @@ -0,0 +1,237 @@ +# Java Client For Nutanix Files APIs + +The Java client for Nutanix Files APIs is designed for Java client application developers offering them simple and flexible access to APIs that 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. +## 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 +- Package version: 4.0.1 + +## Requirements. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + files-java-client + 4.0.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:files-java-client:4.0.1") +} +``` + +## Configuration + +The Java client for Nutanix Files 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.fil.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.fil.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.fil.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.fil.java.client.ApiClient; +import com.nutanix.fil.java.client.api.AntivirusServersApi; +import com.nutanix.dp1.fil.files.v4.config.GetAntivirusServerApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + AntivirusServersApi antivirusServersApi = new AntivirusServersApi(client); + String fileServerExtId = "cDBFEdfD-faBF-bF8c-bddb-fCE51Baf2F9d"; + String extId = "ccb49eAe-a59F-0FD1-52aE-Fef45d08831D"; + = antivirusServersApi.getAntivirusServerById(fileServerExtId, extId); + } +} +``` + +### 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. + +```java +import com.nutanix.fil.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.fil.java.client.ApiClient; +import com.nutanix.dp1.fil.files.v4.config.GetAntivirusServerApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + AntivirusServersApi antivirusServersApi = new AntivirusServersApi(client); + String fileServerExtId = "cDBFEdfD-faBF-bF8c-bddb-fCE51Baf2F9d"; + String extId = "ccb49eAe-a59F-0FD1-52aE-Fef45d08831D"; + = antivirusServersApi.getAntivirusServerById(fileServerExtId, extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(); + // ... + // Perform update call with received E-Tag reference + AntivirusServer antivirusServer = (AntivirusServer) .getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + antivirusServersApi.updateAntivirusServerById(antivirusServerfileServerExtId, extId, , opts); + } +} + +``` + +### 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](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 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 +// this sample code is not usable directly for real use-case + +import com.nutanix.fil.java.client.ApiClient; +import com.nutanix.fil.java.client.api.SampleApi; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + SampleApi sampleApi = new SampleApi(client); + final String extId = '66673023168b486898d76bc27e5ce9c2'; + SampleGetResponse sampleResponse = sampleApi.listSample(pageValue, //$page + limitValue, //$limit + filterValue, //$filter + orderbyValue, //$orderby + selectValue, //$select + expandValue //$expand + ); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=files&version=v4.0&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/iam/README.md b/iam/README.md index ba37798..ace5c2b 100644 --- a/iam/README.md +++ b/iam/README.md @@ -1,6 +1,6 @@ -# Java Client For Nutanix Iam Versioned APIs +# Java Client For Nutanix Identity and Access Management APIs -The Java client for Nutanix Iam Versioned APIs is designed for Java client application developers offering them simple and flexible access to APIs that identity and Access Management in Nutanix cluster. +The Java client for Nutanix Identity and Access Management APIs is designed for Java client application developers offering them simple and flexible access to APIs that nutanix APIs for managing users, user-groups, directory services, identity providers, roles and authorization policies. ## Features - Invoke Nutanix APIs with a simple interface. - Handle Authentication seamlessly. @@ -8,8 +8,28 @@ The Java client for Nutanix Iam Versioned APIs is designed for Java client appli - Use standard methods for installation. ## Version -- API version: v4.0.a1 -- Package version: 4.0.2-alpha-1 +- API version: v4.1.b2 +- Package version: 4.1.1-beta-2 + +## 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.iam.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. @@ -28,7 +48,7 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or com.nutanix.api iam-java-client - 4.0.2-alpha-1 + 4.1.1-beta-2 ``` @@ -36,13 +56,13 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or ```groovy dependencies { - implementation("com.nutanix.api:iam-java-client:4.0.2-alpha-1") + implementation("com.nutanix.api:iam-java-client:4.1.1-beta-2") } ``` ## Configuration -The Java client for Nutanix Iam Versioned APIs can be configured with the following parameters +The Java client for Nutanix Identity and Access Management APIs can be configured with the following parameters | Parameter | Description | Required | Default Value| |-----------|----------------------------------------------------------------------------------|----------|--------------| @@ -57,6 +77,7 @@ The Java client for Nutanix Iam Versioned APIs can be configured with the follow | 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 @@ -76,13 +97,35 @@ 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.iam.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.iam.java.client.ApiClient; @@ -90,7 +133,7 @@ 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 } } ``` @@ -101,7 +144,7 @@ public class Sample { ```java import com.nutanix.iam.java.client.ApiClient; -import com.nutanix.iam.java.client.api.CertAuthProviderApi; +import com.nutanix.iam.java.client.api.CertificateAuthenticationProvidersApi; import com.nutanix.dp1.iam.iam.v4.authn.GetCertAuthProviderApiResponse; public class Sample { @@ -109,9 +152,9 @@ public class Sample { ApiClient client = new ApiClient(); // Configure the client // ... - CertAuthProviderApi certAuthProviderApi = new CertAuthProviderApi(client); - String extId = "bc5eaFc6-2114-A1AC-EdDA-99b0eECeE4eb"; - GetCertAuthProviderApiResponse getCertAuthProviderApiResponse = certAuthProviderApi.HandleGetCertAuthProvider(extId); + CertificateAuthenticationProvidersApi certificateAuthenticationProvidersApi = new CertificateAuthenticationProvidersApi(client); + String extId = "EEdD8aa4-4CCA-b39c-f8DF-aEd7F30FFBfA"; + GetCertAuthProviderApiResponse getCertAuthProviderApiResponse = certificateAuthenticationProvidersApi.getCertAuthProviderById(extId); } } ``` @@ -145,9 +188,9 @@ public class Sample { // Configure the client // ... // perform GET call - CertAuthProviderApi certAuthProviderApi = new CertAuthProviderApi(client); - String extId = "bc5eaFc6-2114-A1AC-EdDA-99b0eECeE4eb"; - GetCertAuthProviderApiResponse getCertAuthProviderApiResponse = certAuthProviderApi.HandleGetCertAuthProvider(extId); + CertificateAuthenticationProvidersApi certificateAuthenticationProvidersApi = new CertificateAuthenticationProvidersApi(client); + String extId = "EEdD8aa4-4CCA-b39c-f8DF-aEd7F30FFBfA"; + GetCertAuthProviderApiResponse getCertAuthProviderApiResponse = certificateAuthenticationProvidersApi.getCertAuthProviderById(extId); // Extract E-Tag Header final String eTagHeader = ApiClient.getEtag(getCertAuthProviderApiResponse); // ... @@ -156,7 +199,7 @@ public class Sample { // initialize/change parameters for update HashMap opts = new HashMap<>(); opts.put("If-Match", eTagHeader); - certAuthProviderApi.HandleUpdateCertAuthProvider(certAuthProvider, extId, opts); + certificateAuthenticationProvidersApi.updateCertAuthProviderById(certAuthProviderextId, , opts); } } @@ -171,25 +214,27 @@ 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.iam.java.client.ApiClient; -import com.nutanix.iam.java.client.api.CertAuthProviderApi; -import com.nutanix.dp1.iam.iam.v4.authn.ListCertAuthProviderApiResponse; +import com.nutanix.iam.java.client.api.DirectoryServicesApi; +import com.nutanix.dp1.iam.iam.v4.authn.ListDirectoryServicesApiResponse; public class Sample { public void performOperation() { ApiClient client = new ApiClient(); // Configure the client // ... - CertAuthProviderApi certAuthProviderApi = new CertAuthProviderApi(client); - String null = "string_sample_data"; - String null = "string_sample_data"; - String null = "string_sample_data"; - ListCertAuthProviderApiResponse listCertAuthProviderApiResponse = certAuthProviderApi.HandleListCertAuthProviders(null, null, null); + DirectoryServicesApi directoryServicesApi = new DirectoryServicesApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String select = null; + ListDirectoryServicesApiResponse listDirectoryServicesApiResponse = directoryServicesApi.listDirectoryServices(page, limit, filter, orderby, select); } } ``` @@ -198,10 +243,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=iam&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=iam&version=v4.1.b2&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:sdk@nutanix.com) \ No newline at end of file diff --git a/lcm/README.md b/lcm/README.md new file mode 100644 index 0000000..b83630d --- /dev/null +++ b/lcm/README.md @@ -0,0 +1,204 @@ +# Java Client For Nutanix Lcm Versioned APIs + +The Java client for Nutanix Lcm Versioned APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage Infrastructure, Software and Firmware Upgrades. +## 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.1-alpha-1 + +## Requirements. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + lcm-java-client + 4.0.1-alpha-1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:lcm-java-client:4.0.1-alpha-1") +} +``` + +## Configuration + +The Java client for Nutanix Lcm Versioned APIs can be configured with the following parameters + +| Parameter | Description | Required | Default Value| +|-----------|----------------------------------------------------------------------------------|----------|--------------| +| 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 | +| debugging | 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 | +| timeout | Global timeout in milliseconds for all operations | No | 30000 | + +### Sample Configuration + +```java +import com.nutanix.lcm.java.client.ApiClient; + +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 + } +} +``` + +### 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) +- [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) +```java +import com.nutanix.lcm.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 + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.lcm.java.client.ApiClient; +import com.nutanix.lcm.java.client.api.BundlesApi; +import com.nutanix.dp1.lcm.lcm.v4.resources.GetBundleInfoApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + BundlesApi bundlesApi = new BundlesApi(client); + String uuid = "^5fAF5EdC-d1C4-58B0-44BA-5EDE8dAFE0Ba$"; + GetBundleInfoApiResponse getBundleInfoApiResponse = bundlesApi.getBundle(uuid); + } +} +``` + +### 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. + +```java +import com.nutanix.lcm.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.lcm.java.client.ApiClient; +import com.nutanix.dp1.lcm.lcm.v4.resources.GetBundleInfoApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + BundlesApi bundlesApi = new BundlesApi(client); + String uuid = "^5fAF5EdC-d1C4-58B0-44BA-5EDE8dAFE0Ba$"; + GetBundleInfoApiResponse getBundleInfoApiResponse = bundlesApi.getBundle(uuid); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(getBundleInfoApiResponse); + // ... + // Perform update call with received E-Tag reference + byte[] requestBody = (byte[]) getBundleInfoApiResponse.getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + bundlesApi.putBundle(requestBody, uuid, opts); + } +} + +``` + +### 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 be set to its nearest bound. In other words, a page number of less than 0 would be set to 0 and a page number greater than the total available pages would be set to the last page.| +| $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 be set to the default maximum number of records, which is 100. | +| $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. | + +List Options can be passed to list operations in order to perform pagination, filtering etc. +```java +import com.nutanix.lcm.java.client.ApiClient; +import com.nutanix.lcm.java.client.api.BundlesApi; +import com.nutanix.dp1.lcm.lcm.v4.resources.GetBundlesApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + BundlesApi bundlesApi = new BundlesApi(client); + int $page = 0; + int $limit = 50; + String $filter = "string_sample_data"; + GetBundlesApiResponse getBundlesApiResponse = bundlesApi.getBundles($page, $limit, $filter); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has 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](@sdk@nutanix.com) \ No newline at end of file diff --git a/licensing/README.md b/licensing/README.md new file mode 100644 index 0000000..8f96913 --- /dev/null +++ b/licensing/README.md @@ -0,0 +1,252 @@ +# Java Client For Nutanix Licensing APIs + +The Java client for Nutanix Licensing APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage licenses for your clusters and Prism Central, get information on applied licenses, license compliance details and feature entitlements. +## Features +- Invoke Nutanix APIs with a simple interface. +- Handle Authentication seamlessly. +- Reduce boilerplate code implementation. +- Use standard methods for installation. +## Version + +- API version: v4.3 +- Package version: 4.3.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.lic.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + licensing-java-client + 4.3.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:licensing-java-client:4.3.1") +} +``` + +## Configuration + +The Java client for Nutanix Licensing 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.lic.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.lic.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.lic.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +// this sample code is not usable directly for real use-case + +import com.nutanix.lic.java.client.ApiClient; +import com.nutanix.lic.java.client.api.SampleApi; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + SampleApi sampleApi = new SampleApi(client); + final String extId = '66673023168b486898d76bc27e5ce9c2'; + SampleGetResponse sampleResponse = sampleApi.getSampleByExtId(extId); + } +} +``` + +### 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. + +```java +import com.nutanix.lic.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.lic.java.client.ApiClient; + +// this sample code is not usable directly for real use-case + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + SampleApi samplesApi = new SampleApi(client); + final String extId = '66673023168b486898d76bc27e5ce9c2'; + SampleGetResponse sampleResponse = samplesApi.getSampleByExtId(extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(sampleResponse); + // ... + Sample body = (Sample) sampleResponse.getData(); + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + samplesApi.updateSampleByExtId(body,extId,opts); + } +} + +``` + +### 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](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 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.lic.java.client.ApiClient; +import com.nutanix.lic.java.client.api.LicenseKeysApi; +import com.nutanix.dp1.lic.licensing.v4.config.ListLicenseKeysApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + LicenseKeysApi licenseKeysApi = new LicenseKeysApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String expand = null; + String select = null; + ListLicenseKeysApiResponse listLicenseKeysApiResponse = licenseKeysApi.listLicenseKeys(page, limit, filter, orderby, expand, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=licensing&version=v4.3&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/lifecycle/README.md b/lifecycle/README.md new file mode 100644 index 0000000..4e15233 --- /dev/null +++ b/lifecycle/README.md @@ -0,0 +1,251 @@ +# Java Client For Nutanix Lifecycle Management APIs + +The Java client for Nutanix Lifecycle Management APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage Infrastructure, Software and Firmware Upgrades. +## Features +- Invoke Nutanix APIs with a simple interface. +- Handle Authentication seamlessly. +- Reduce boilerplate code implementation. +- Use standard methods for installation. +## Version + +- API version: v4.2 +- Package version: 4.2.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.lif.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + lifecycle-java-client + 4.2.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:lifecycle-java-client:4.2.1") +} +``` + +## Configuration + +The Java client for Nutanix Lifecycle Management 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.lif.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.lif.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.lif.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +// this sample code is not usable directly for real use-case + +import com.nutanix.lif.java.client.ApiClient; +import com.nutanix.lif.java.client.api.SampleApi; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + SampleApi sampleApi = new SampleApi(client); + final String extId = '66673023168b486898d76bc27e5ce9c2'; + SampleGetResponse sampleResponse = sampleApi.getSampleByExtId(extId); + } +} +``` + +### 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. + +```java +import com.nutanix.lif.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.lif.java.client.ApiClient; + +// this sample code is not usable directly for real use-case + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + SampleApi samplesApi = new SampleApi(client); + final String extId = '66673023168b486898d76bc27e5ce9c2'; + SampleGetResponse sampleResponse = samplesApi.getSampleByExtId(extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(sampleResponse); + // ... + Sample body = (Sample) sampleResponse.getData(); + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + samplesApi.updateSampleByExtId(body,extId,opts); + } +} + +``` + +### 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](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 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.lif.java.client.ApiClient; +import com.nutanix.lif.java.client.api.BundlesApi; +import com.nutanix.dp1.lif.lifecycle.v4.resources.ListBundlesApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + BundlesApi bundlesApi = new BundlesApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String select = null; + ListBundlesApiResponse listBundlesApiResponse = bundlesApi.listBundles(page, limit, filter, orderby, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=lifecycle&version=v4.2&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/microseg/README.md b/microseg/README.md new file mode 100644 index 0000000..61b36f3 --- /dev/null +++ b/microseg/README.md @@ -0,0 +1,252 @@ +# Java Client For Nutanix Flow Management APIs + +The Java client for Nutanix Flow Management APIs is designed for Java 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.2 +- Package version: 4.2.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.mic.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + microseg-java-client + 4.2.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:microseg-java-client:4.2.1") +} +``` + +## Configuration + +The Java client for Nutanix Flow Management 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.mic.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.mic.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.mic.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.mic.java.client.ApiClient; +import com.nutanix.mic.java.client.api.AddressGroupsApi; +import com.nutanix.dp1.mic.microseg.v4.config.GetAddressGroupApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + AddressGroupsApi addressGroupsApi = new AddressGroupsApi(client); + String extId = "eE5EFe7f-1eC2-f9eD-4eb5-FDAA6AF74bfb"; + GetAddressGroupApiResponse getAddressGroupApiResponse = addressGroupsApi.getAddressGroupById(extId); + } +} +``` + +### 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. + +```java +import com.nutanix.mic.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.mic.java.client.ApiClient; +import com.nutanix.dp1.mic.microseg.v4.config.GetAddressGroupApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + AddressGroupsApi addressGroupsApi = new AddressGroupsApi(client); + String extId = "eE5EFe7f-1eC2-f9eD-4eb5-FDAA6AF74bfb"; + GetAddressGroupApiResponse getAddressGroupApiResponse = addressGroupsApi.getAddressGroupById(extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(getAddressGroupApiResponse); + // ... + // Perform update call with received E-Tag reference + AddressGroup addressGroup = (AddressGroup) getAddressGroupApiResponse.getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + addressGroupsApi.updateAddressGroupById(addressGroupextId, , opts); + } +} + +``` + +### 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](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 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.mic.java.client.ApiClient; +import com.nutanix.mic.java.client.api.AddressGroupsApi; +import com.nutanix.dp1.mic.microseg.v4.config.ListAddressGroupsApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + AddressGroupsApi addressGroupsApi = new AddressGroupsApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String select = null; + ListAddressGroupsApiResponse listAddressGroupsApiResponse = addressGroupsApi.listAddressGroups(page, limit, filter, orderby, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=microseg&version=v4.2&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/monitoring/README.md b/monitoring/README.md new file mode 100644 index 0000000..191ab84 --- /dev/null +++ b/monitoring/README.md @@ -0,0 +1,254 @@ +# Java Client For Nutanix Monitoring APIs + +The Java client for Nutanix Monitoring APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage Alerts, Alert policies, Events and Audits. +## Features +- Invoke Nutanix APIs with a simple interface. +- Handle Authentication seamlessly. +- Reduce boilerplate code implementation. +- Use standard methods for installation. +## Version + +- API version: v4.2 +- Package version: 4.2.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.mon.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + monitoring-java-client + 4.2.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:monitoring-java-client:4.2.1") +} +``` + +## Configuration + +The Java client for Nutanix Monitoring 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.mon.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.mon.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.mon.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.mon.java.client.ApiClient; +import com.nutanix.mon.java.client.api.SystemDefinedPoliciesApi; +import com.nutanix.dp1.mon.monitoring.v4.serviceability.GetClusterConfigApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + SystemDefinedPoliciesApi systemDefinedPoliciesApi = new SystemDefinedPoliciesApi(client); + String systemDefinedPolicyExtId = "54329"; + String extId = "9134caB1-C6FB-9E0f-A388-C47140720ddD"; + GetClusterConfigApiResponse getClusterConfigApiResponse = systemDefinedPoliciesApi.getClusterConfigById(systemDefinedPolicyExtId, extId); + } +} +``` + +### 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. + +```java +import com.nutanix.mon.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.mon.java.client.ApiClient; +import com.nutanix.dp1.mon.monitoring.v4.serviceability.GetClusterConfigApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + SystemDefinedPoliciesApi systemDefinedPoliciesApi = new SystemDefinedPoliciesApi(client); + String systemDefinedPolicyExtId = "54329"; + String extId = "9134caB1-C6FB-9E0f-A388-C47140720ddD"; + GetClusterConfigApiResponse getClusterConfigApiResponse = systemDefinedPoliciesApi.getClusterConfigById(systemDefinedPolicyExtId, extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(getClusterConfigApiResponse); + // ... + // Perform update call with received E-Tag reference + ClusterConfig clusterConfig = (ClusterConfig) getClusterConfigApiResponse.getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + systemDefinedPoliciesApi.updateClusterConfigById(clusterConfigsystemDefinedPolicyExtId, extId, , opts); + } +} + +``` + +### 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](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 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.mon.java.client.ApiClient; +import com.nutanix.mon.java.client.api.AlertsApi; +import com.nutanix.dp1.mon.monitoring.v4.serviceability.ListAlertsApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + AlertsApi alertsApi = new AlertsApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String select = null; + ListAlertsApiResponse listAlertsApiResponse = alertsApi.listAlerts(page, limit, filter, orderby, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=monitoring&version=v4.2&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/multidomain/README.md b/multidomain/README.md new file mode 100644 index 0000000..c28a784 --- /dev/null +++ b/multidomain/README.md @@ -0,0 +1,252 @@ +# Java Client For Nutanix Multidomain Versioned APIs + +The Java client for Nutanix Multidomain Versioned APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage all Nutanix services running on the Nutanix Cloud Platform (NCP) deployed in on-prem data centers ,Nutanix Cloud Clusters (NC2) or edge sites. +## Features +- Invoke Nutanix APIs with a simple interface. +- Handle Authentication seamlessly. +- Reduce boilerplate code implementation. +- Use standard methods for installation. +## Version + +- API version: v4.2 +- Package version: 4.2.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.mul.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + multidomain-java-client + 4.2.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:multidomain-java-client:4.2.1") +} +``` + +## Configuration + +The Java client for Nutanix Multidomain 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.mul.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.mul.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.mul.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.mul.java.client.ApiClient; +import com.nutanix.mul.java.client.api.ExternalRepositoriesApi; +import com.nutanix.dp1.mul.multidomain.v4.config.GetExternalRepositoryApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + ExternalRepositoriesApi externalRepositoriesApi = new ExternalRepositoriesApi(client); + String extId = "BabEb42d-0DDe-69fD-DBeA-CDF3Fb2090A4"; + GetExternalRepositoryApiResponse getExternalRepositoryApiResponse = externalRepositoriesApi.getExternalRepositoryById(extId); + } +} +``` + +### 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. + +```java +import com.nutanix.mul.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.mul.java.client.ApiClient; +import com.nutanix.dp1.mul.multidomain.v4.config.GetExternalRepositoryApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + ExternalRepositoriesApi externalRepositoriesApi = new ExternalRepositoriesApi(client); + String extId = "BabEb42d-0DDe-69fD-DBeA-CDF3Fb2090A4"; + GetExternalRepositoryApiResponse getExternalRepositoryApiResponse = externalRepositoriesApi.getExternalRepositoryById(extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(getExternalRepositoryApiResponse); + // ... + // Perform update call with received E-Tag reference + ExternalRepository externalRepository = (ExternalRepository) getExternalRepositoryApiResponse.getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + externalRepositoriesApi.updateExternalRepositoryById(externalRepositoryextId, , opts); + } +} + +``` + +### 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](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 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.mul.java.client.ApiClient; +import com.nutanix.mul.java.client.api.ExternalRepositoriesApi; +import com.nutanix.dp1.mul.multidomain.v4.config.ListExternalRepositoriesApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + ExternalRepositoriesApi externalRepositoriesApi = new ExternalRepositoriesApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String select = null; + ListExternalRepositoriesApiResponse listExternalRepositoriesApiResponse = externalRepositoriesApi.listExternalRepositories(page, limit, filter, orderby, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=multidomain&version=v4.2&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/networking/README.md b/networking/README.md index 29d6d8f..376bad2 100644 --- a/networking/README.md +++ b/networking/README.md @@ -1,6 +1,6 @@ -# Java Client For Nutanix Networking Versioned APIs +# Java Client For Nutanix Networking APIs -The Java client for Nutanix Networking Versioned APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage networking configuration on Nutanix clusters, including AHV and advanced networking. +The Java client for Nutanix Networking APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage networking configuration on Nutanix clusters, including AHV and advanced networking. ## Features - Invoke Nutanix APIs with a simple interface. - Handle Authentication seamlessly. @@ -8,8 +8,28 @@ The Java client for Nutanix Networking Versioned APIs is designed for Java clien - Use standard methods for installation. ## Version -- API version: v4.0.a1 -- Package version: 4.0.1-alpha-1 +- API version: v4.2 +- Package version: 4.2.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.net.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. @@ -28,7 +48,7 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or com.nutanix.api networking-java-client - 4.0.1-alpha-1 + 4.2.1 ``` @@ -36,13 +56,13 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or ```groovy dependencies { - implementation("com.nutanix.api:networking-java-client:4.0.1-alpha-1") + implementation("com.nutanix.api:networking-java-client:4.2.1") } ``` ## Configuration -The Java client for Nutanix Networking Versioned APIs can be configured with the following parameters +The Java client for Nutanix Networking APIs can be configured with the following parameters | Parameter | Description | Required | Default Value| |-----------|----------------------------------------------------------------------------------|----------|--------------| @@ -57,6 +77,7 @@ The Java client for Nutanix Networking Versioned APIs can be configured with the | 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 @@ -76,13 +97,35 @@ 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.net.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.net.java.client.ApiClient; @@ -90,7 +133,7 @@ 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 } } ``` @@ -139,7 +182,6 @@ Nutanix APIs require that concurrent updates are protected using [ETag](https:// ```java import com.nutanix.net.java.client.ApiClient; - // this sample code is not usable directly for real use-case public class Sample { @@ -171,26 +213,27 @@ 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.net.java.client.ApiClient; -import com.nutanix.net.java.client.api.BgpSessionApi; -import com.nutanix.dp1.net.networking.v4.config.BgpSessionListApiResponse; +import com.nutanix.net.java.client.api.AwsSubnetsApi; +import com.nutanix.dp1.net.networking.v4.aws.config.ListAwsSubnetsApiResponse; public class Sample { public void performOperation() { ApiClient client = new ApiClient(); // Configure the client // ... - BgpSessionApi bgpSessionApi = new BgpSessionApi(client); + AwsSubnetsApi awsSubnetsApi = new AwsSubnetsApi(client); int page = 0; int limit = 50; - String null = "string_sample_data"; - String null = "string_sample_data"; - BgpSessionListApiResponse bgpSessionListApiResponse = bgpSessionApi.listBgpSessions(page, limit, null, null); + String filter = null; + String orderby = null; + String select = null; + ListAwsSubnetsApiResponse listAwsSubnetsApiResponse = awsSubnetsApi.listAwsSubnets(page, limit, filter, orderby, select); } } ``` @@ -199,10 +242,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=networking&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=networking&version=v4.2&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:sdk@nutanix.com) \ No newline at end of file diff --git a/ntnxsaas/README.md b/ntnxsaas/README.md new file mode 100644 index 0000000..3fb05e3 --- /dev/null +++ b/ntnxsaas/README.md @@ -0,0 +1,177 @@ +# Java Client For Nutanix Ntnxsaas Versioned APIs + +The Java client for Nutanix Ntnxsaas Versioned APIs is designed for Java client application developers offering them simple and flexible access to APIs that allow businesses to streamline operations by providing scalable solutions for subscription management, billing automation, customer support, and partner services. +## 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.1-alpha-1 + +## Requirements. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + ntnxsaas-java-client + 4.0.1-alpha-1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:ntnxsaas-java-client:4.0.1-alpha-1") +} +``` + +## Configuration + +The Java client for Nutanix Ntnxsaas 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.ntn.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.ntn.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.ntn.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +``` + +### 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. + +```java +import com.nutanix.ntn.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java + +``` + +### 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](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 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 +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=ntnxsaas&version=v4.0.a1&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/objects/README.md b/objects/README.md new file mode 100644 index 0000000..24458ba --- /dev/null +++ b/objects/README.md @@ -0,0 +1,233 @@ +# Java Client For Nutanix Objects Storage Management APIs + +The Java client for Nutanix Objects Storage Management APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage Petabytes of Unstructured and Machine-generated data using a software-defined Object Store Service. +## 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 +- Package version: 4.0.1 + +## Requirements. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + objects-java-client + 4.0.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:objects-java-client:4.0.1") +} +``` + +## Configuration + +The Java client for Nutanix Objects Storage Management 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.obj.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.obj.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.obj.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.obj.java.client.ApiClient; +import com.nutanix.obj.java.client.api.ObjectStoresApi; +import com.nutanix.dp1.obj.objects.v4.config.GetObjectstoreApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + ObjectStoresApi objectStoresApi = new ObjectStoresApi(client); + String extId = "8Ee8Fdf9-ADcC-71Db-ef6C-eDAFB7EE9BAb"; + = objectStoresApi.getObjectstoreById(extId); + } +} +``` + +### 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. + +```java +import com.nutanix.obj.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.obj.java.client.ApiClient; +import com.nutanix.dp1.obj.objects.v4.config.GetObjectstoreApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + ObjectStoresApi objectStoresApi = new ObjectStoresApi(client); + String extId = "8Ee8Fdf9-ADcC-71Db-ef6C-eDAFB7EE9BAb"; + = objectStoresApi.getObjectstoreById(extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(); + // ... + // Perform update call with received E-Tag reference + ObjectStore objectStore = (ObjectStore) .getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + objectStoresApi.updateObjectstoreById(objectStoreextId, , opts); + } +} + +``` + +### 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](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 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.obj.java.client.ApiClient; +import com.nutanix.obj.java.client.api.ObjectStoresApi; +import com.nutanix.dp1.obj.objects.v4.config.ListObjectstoresApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + ObjectStoresApi objectStoresApi = new ObjectStoresApi(client); + int page = 0; + int limit = 50; + String null = "string_sample_data"; + String null = "string_sample_data"; + String null = "string_sample_data"; + String null = "string_sample_data"; + = objectStoresApi.listObjectstores(page, limit, null, null, null, null); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=objects&version=v4.0&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/opsmgmt/README.md b/opsmgmt/README.md new file mode 100644 index 0000000..8cf440c --- /dev/null +++ b/opsmgmt/README.md @@ -0,0 +1,252 @@ +# Java Client For Nutanix Cloud Management Platform APIs + +The Java client for Nutanix Cloud Management Platform APIs is designed for Java client application developers offering them simple and flexible access to APIs that provide functionalities that are common to APIs in namespaces aiops, devops, secops, finops. +## 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 +- Package version: 4.0.3 + +## 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.ops.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + opsmgmt-java-client + 4.0.3 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:opsmgmt-java-client:4.0.3") +} +``` + +## Configuration + +The Java client for Nutanix Cloud Management Platform 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.ops.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.ops.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.ops.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.ops.java.client.ApiClient; +import com.nutanix.ops.java.client.api.ReportConfigApi; +import com.nutanix.dp1.ops.opsmgmt.v4.config.GetReportConfigApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + ReportConfigApi reportConfigApi = new ReportConfigApi(client); + String extId = "B7EFD8fc-aCdA-3e1c-A9AC-bc8bEadaF44f"; + GetReportConfigApiResponse getReportConfigApiResponse = reportConfigApi.getReportConfigById(extId); + } +} +``` + +### 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. + +```java +import com.nutanix.ops.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.ops.java.client.ApiClient; +import com.nutanix.dp1.ops.opsmgmt.v4.config.GetReportConfigApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + ReportConfigApi reportConfigApi = new ReportConfigApi(client); + String extId = "B7EFD8fc-aCdA-3e1c-A9AC-bc8bEadaF44f"; + GetReportConfigApiResponse getReportConfigApiResponse = reportConfigApi.getReportConfigById(extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(getReportConfigApiResponse); + // ... + // Perform update call with received E-Tag reference + ReportConfig reportConfig = (ReportConfig) getReportConfigApiResponse.getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + reportConfigApi.updateReportConfigById(reportConfigextId, , opts); + } +} + +``` + +### 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](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 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.ops.java.client.ApiClient; +import com.nutanix.ops.java.client.api.ReportConfigApi; +import com.nutanix.dp1.ops.opsmgmt.v4.config.ListReportConfigsApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + ReportConfigApi reportConfigApi = new ReportConfigApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String select = null; + ListReportConfigsApiResponse listReportConfigsApiResponse = reportConfigApi.listReportConfigs(page, limit, filter, orderby, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=opsmgmt&version=v4.0&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/prism/README.md b/prism/README.md index 07d2782..03e5fa4 100644 --- a/prism/README.md +++ b/prism/README.md @@ -1,6 +1,6 @@ -# Java Client For Nutanix Prism Versioned APIs +# Java Client For Nutanix Prism APIs -The Java client for Nutanix Prism Versioned APIs is designed for Java client application developers offering them simple and flexible access to APIs that task Management, Category Associations, Prism Central DR, Alerts, Alert policies, Events and Audits. +The Java client for Nutanix Prism APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage Tasks, Category Associations and Submit Batch Operations. ## Features - Invoke Nutanix APIs with a simple interface. - Handle Authentication seamlessly. @@ -8,8 +8,28 @@ The Java client for Nutanix Prism Versioned APIs is designed for Java client app - Use standard methods for installation. ## Version -- API version: v4.0.a1 -- Package version: 4.0.2-alpha-1 +- API version: v4.2 +- Package version: 4.2.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.pri.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. @@ -28,7 +48,7 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or com.nutanix.api prism-java-client - 4.0.2-alpha-1 + 4.2.1 ``` @@ -36,13 +56,13 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or ```groovy dependencies { - implementation("com.nutanix.api:prism-java-client:4.0.2-alpha-1") + implementation("com.nutanix.api:prism-java-client:4.2.1") } ``` ## Configuration -The Java client for Nutanix Prism Versioned APIs can be configured with the following parameters +The Java client for Nutanix Prism APIs can be configured with the following parameters | Parameter | Description | Required | Default Value| |-----------|----------------------------------------------------------------------------------|----------|--------------| @@ -57,6 +77,7 @@ The Java client for Nutanix Prism 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 @@ -76,13 +97,35 @@ 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.pri.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.pri.java.client.ApiClient; @@ -90,7 +133,7 @@ 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 } } ``` @@ -101,18 +144,18 @@ public class Sample { ```java import com.nutanix.pri.java.client.ApiClient; -import com.nutanix.pri.java.client.api.SystemDefinedPoliciesApi; -import com.nutanix.dp1.pri.prism.v4.policies.GetSdaPolicyApiResponse; +import com.nutanix.pri.java.client.api.CategoriesApi; +import com.nutanix.dp1.pri.prism.v4.config.GetCategoryApiResponse; public class Sample { public void performOperation() { ApiClient client = new ApiClient(); // Configure the client // ... - SystemDefinedPoliciesApi systemDefinedPoliciesApi = new SystemDefinedPoliciesApi(client); - String entityUid = "string_sample_data"; - boolean globalConfig = true; - GetSdaPolicyApiResponse getSdaPolicyApiResponse = systemDefinedPoliciesApi.getSdaPolicyById(entityUid, globalConfig); + CategoriesApi categoriesApi = new CategoriesApi(client); + String extId = "3eD33FAF-Cb20-DF7c-73fe-caBe0fdd2f3B"; + String expand = null; + GetCategoryApiResponse getCategoryApiResponse = categoriesApi.getCategoryById(extId, expand); } } ``` @@ -138,7 +181,7 @@ You can also modify the headers sent with each individual operation: Nutanix APIs require that concurrent updates are protected using [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. ```java import com.nutanix.pri.java.client.ApiClient; -import com.nutanix.dp1.pri.prism.v4.policies.GetSdaPolicyApiResponse; +import com.nutanix.dp1.pri.prism.v4.config.GetCategoryApiResponse; public class Sample { public void performOperation() { @@ -146,19 +189,19 @@ public class Sample { // Configure the client // ... // perform GET call - SystemDefinedPoliciesApi systemDefinedPoliciesApi = new SystemDefinedPoliciesApi(client); - String entityUid = "string_sample_data"; - boolean globalConfig = true; - GetSdaPolicyApiResponse getSdaPolicyApiResponse = systemDefinedPoliciesApi.getSdaPolicyById(entityUid, globalConfig); + CategoriesApi categoriesApi = new CategoriesApi(client); + String extId = "3eD33FAF-Cb20-DF7c-73fe-caBe0fdd2f3B"; + String expand = null; + GetCategoryApiResponse getCategoryApiResponse = categoriesApi.getCategoryById(extId, expand); // Extract E-Tag Header - final String eTagHeader = ApiClient.getEtag(getSdaPolicyApiResponse); + final String eTagHeader = ApiClient.getEtag(getCategoryApiResponse); // ... // Perform update call with received E-Tag reference - SystemDefined systemDefined = (SystemDefined) getSdaPolicyApiResponse.getData(); + byte[] requestBody = (byte[]) getCategoryApiResponse.getData(); // initialize/change parameters for update HashMap opts = new HashMap<>(); opts.put("If-Match", eTagHeader); - systemDefinedPoliciesApi.updateSdaPolicy(systemDefined, entityUid, opts); + categoriesApi.updateCategoryById(requestBodyextId, , opts); } } @@ -173,26 +216,27 @@ 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.pri.java.client.ApiClient; -import com.nutanix.pri.java.client.api.AlertsApi; -import com.nutanix.dp1.pri.prism.v4.alerts.AlertListApiResponse; +import com.nutanix.pri.java.client.api.BatchesApi; +import com.nutanix.dp1.pri.prism.v4.operations.ListBatchesApiResponse; public class Sample { public void performOperation() { ApiClient client = new ApiClient(); // Configure the client // ... - AlertsApi alertsApi = new AlertsApi(client); + BatchesApi batchesApi = new BatchesApi(client); int page = 0; int limit = 50; - String null = "string_sample_data"; - String null = "string_sample_data"; - AlertListApiResponse alertListApiResponse = alertsApi.getAlerts(page, limit, null, null); + String filter = null; + String orderby = null; + String select = null; + ListBatchesApiResponse listBatchesApiResponse = batchesApi.listBatches(page, limit, filter, orderby, select); } } ``` @@ -201,10 +245,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=prism&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=prism&version=v4.2&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:sdk@nutanix.com) \ No newline at end of file diff --git a/security/README.md b/security/README.md new file mode 100644 index 0000000..7b4813a --- /dev/null +++ b/security/README.md @@ -0,0 +1,252 @@ +# Java Client For Nutanix Security APIs + +The Java client for Nutanix Security APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage security features, such as encryption, certificates, or platform hardening. +## Features +- Invoke Nutanix APIs with a simple interface. +- Handle Authentication seamlessly. +- Reduce boilerplate code implementation. +- Use standard methods for installation. +## Version + +- API version: v4.1 +- Package version: 4.1.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.sec.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + security-java-client + 4.1.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:security-java-client:4.1.1") +} +``` + +## Configuration + +The Java client for Nutanix Security 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.sec.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.sec.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.sec.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.sec.java.client.ApiClient; +import com.nutanix.sec.java.client.api.CredentialsApi; +import com.nutanix.dp1.sec.security.v4.config.GetCredentialApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + CredentialsApi credentialsApi = new CredentialsApi(client); + String extId = "8319db0C-EfDC-1FEb-4caB-dD140EDe087B"; + GetCredentialApiResponse getCredentialApiResponse = credentialsApi.getCredentialById(extId); + } +} +``` + +### 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. + +```java +import com.nutanix.sec.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.sec.java.client.ApiClient; +import com.nutanix.dp1.sec.security.v4.config.GetCredentialApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + CredentialsApi credentialsApi = new CredentialsApi(client); + String extId = "8319db0C-EfDC-1FEb-4caB-dD140EDe087B"; + GetCredentialApiResponse getCredentialApiResponse = credentialsApi.getCredentialById(extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(getCredentialApiResponse); + // ... + // Perform update call with received E-Tag reference + Credential credential = (Credential) getCredentialApiResponse.getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + credentialsApi.updateCredentialById(credentialextId, , opts); + } +} + +``` + +### 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](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 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.sec.java.client.ApiClient; +import com.nutanix.sec.java.client.api.CredentialsApi; +import com.nutanix.dp1.sec.security.v4.config.ListCredentialsApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + CredentialsApi credentialsApi = new CredentialsApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String select = null; + ListCredentialsApiResponse listCredentialsApiResponse = credentialsApi.listCredentials(page, limit, filter, orderby, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=security&version=v4.1&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file diff --git a/vmm/README.md b/vmm/README.md index 273d854..03220d0 100644 --- a/vmm/README.md +++ b/vmm/README.md @@ -1,6 +1,6 @@ -# Java Client For Nutanix Vmm Versioned APIs +# Java Client For Nutanix Virtual Machine Management APIs -The Java client for Nutanix Vmm Versioned APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage the life-cycle of virtual machines hosted on Nutanix. +The Java client for Nutanix Virtual Machine Management APIs is designed for Java client application developers offering them simple and flexible access to APIs that manage the life-cycle of virtual machines hosted on Nutanix. ## Features - Invoke Nutanix APIs with a simple interface. - Handle Authentication seamlessly. @@ -8,8 +8,28 @@ The Java client for Nutanix Vmm Versioned APIs is designed for Java client appli - Use standard methods for installation. ## Version -- API version: v4.0.a1 -- Package version: 4.0.2-alpha-1 +- API version: v4.2 +- Package version: 4.2.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.vmm.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. @@ -28,7 +48,7 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or com.nutanix.api vmm-java-client - 4.0.2-alpha-1 + 4.2.1 ``` @@ -36,13 +56,13 @@ This library is distributed on [Maven Central](https://search.maven.org/). In or ```groovy dependencies { - implementation("com.nutanix.api:vmm-java-client:4.0.2-alpha-1") + implementation("com.nutanix.api:vmm-java-client:4.2.1") } ``` ## Configuration -The Java client for Nutanix Vmm Versioned APIs can be configured with the following parameters +The Java client for Nutanix Virtual Machine Management APIs can be configured with the following parameters | Parameter | Description | Required | Default Value| |-----------|----------------------------------------------------------------------------------|----------|--------------| @@ -57,6 +77,7 @@ The Java client for Nutanix Vmm Versioned APIs can be configured with the follow | 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 @@ -76,13 +97,35 @@ 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.vmm.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.vmm.java.client.ApiClient; @@ -90,7 +133,7 @@ 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 } } ``` @@ -101,18 +144,17 @@ public class Sample { ```java import com.nutanix.vmm.java.client.ApiClient; -import com.nutanix.vmm.java.client.api.VmApi; -import com.nutanix.dp1.vmm.vmm.v4.ahv.config.GetCdromResponse; +import com.nutanix.vmm.java.client.api.ImagesApi; +import com.nutanix.dp1.vmm.vmm.v4.content.GetImageApiResponse; public class Sample { public void performOperation() { ApiClient client = new ApiClient(); // Configure the client // ... - VmApi vmApi = new VmApi(client); - String vmExtId = "CCf0dd4A-beCc-77D1-C18a-6dcDddda7DbA"; - String extId = "F7dFc061-d2eB-Bf1F-DDDa-e55DfBE9B6e1"; - GetCdromResponse getCdromResponse = vmApi.getCdromByExtId(vmExtId, extId); + ImagesApi imagesApi = new ImagesApi(client); + String extId = "BcDBc0Fb-9DaD-DBaB-3BEe-6Cbd6E17eFA5"; + GetImageApiResponse getImageApiResponse = imagesApi.getImageById(extId); } } ``` @@ -138,7 +180,7 @@ You can also modify the headers sent with each individual operation: Nutanix APIs require that concurrent updates are protected using [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. ```java import com.nutanix.vmm.java.client.ApiClient; -import com.nutanix.dp1.vmm.vmm.v4.ahv.config.GetCdromResponse; +import com.nutanix.dp1.vmm.vmm.v4.content.GetImageApiResponse; public class Sample { public void performOperation() { @@ -146,19 +188,18 @@ public class Sample { // Configure the client // ... // perform GET call - VmApi vmApi = new VmApi(client); - String vmExtId = "CCf0dd4A-beCc-77D1-C18a-6dcDddda7DbA"; - String extId = "F7dFc061-d2eB-Bf1F-DDDa-e55DfBE9B6e1"; - GetCdromResponse getCdromResponse = vmApi.getCdromByExtId(vmExtId, extId); + ImagesApi imagesApi = new ImagesApi(client); + String extId = "BcDBc0Fb-9DaD-DBaB-3BEe-6Cbd6E17eFA5"; + GetImageApiResponse getImageApiResponse = imagesApi.getImageById(extId); // Extract E-Tag Header - final String eTagHeader = ApiClient.getEtag(getCdromResponse); + final String eTagHeader = ApiClient.getEtag(getImageApiResponse); // ... // Perform update call with received E-Tag reference - Cdrom cdrom = (Cdrom) getCdromResponse.getData(); + Image image = (Image) getImageApiResponse.getData(); // initialize/change parameters for update HashMap opts = new HashMap<>(); opts.put("If-Match", eTagHeader); - vmApi.updateCdrom(cdrom, vmExtId, extId, opts); + imagesApi.updateImageById(imageextId, , opts); } } @@ -173,26 +214,27 @@ 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.vmm.java.client.ApiClient; -import com.nutanix.vmm.java.client.api.VmApi; -import com.nutanix.dp1.vmm.vmm.v4.ahv.config.ListVmsResponse; +import com.nutanix.vmm.java.client.api.ImagesApi; +import com.nutanix.dp1.vmm.vmm.v4.content.ListImagesApiResponse; public class Sample { public void performOperation() { ApiClient client = new ApiClient(); // Configure the client // ... - VmApi vmApi = new VmApi(client); + ImagesApi imagesApi = new ImagesApi(client); int page = 0; int limit = 50; - String null = "string_sample_data"; - String null = "string_sample_data"; - ListVmsResponse listVmsResponse = vmApi.listVms(page, limit, null, null); + String filter = null; + String orderby = null; + String select = null; + ListImagesApiResponse listImagesApiResponse = imagesApi.listImages(page, limit, filter, orderby, select); } } ``` @@ -201,10 +243,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=vmm&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=vmm&version=v4.2&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:sdk@nutanix.com) \ No newline at end of file diff --git a/volumes/README.md b/volumes/README.md new file mode 100644 index 0000000..9ae4b8f --- /dev/null +++ b/volumes/README.md @@ -0,0 +1,253 @@ +# Java Client For Nutanix Volumes APIs + +The Java client for Nutanix Volumes APIs is designed for Java client application developers offering them simple and flexible access to APIs that configure volumes. +## Features +- Invoke Nutanix APIs with a simple interface. +- Handle Authentication seamlessly. +- Reduce boilerplate code implementation. +- Use standard methods for installation. +## Version + +- API version: v4.2 +- Package version: 4.2.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.vol.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. + +- Maven 3.6 +- Java 8 + +## Usage + +### Installation + +This library is distributed on [Maven Central](https://search.maven.org/). In order to add it as a dependency, please do the following: + +#### Using Maven + +```xml + + com.nutanix.api + volumes-java-client + 4.2.1 + +``` + +#### Using Gradle + +```groovy +dependencies { + implementation("com.nutanix.api:volumes-java-client:4.2.1") +} +``` + +## Configuration + +The Java client for Nutanix Volumes 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 | +| debugging | 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 | +| 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 + +```java +import com.nutanix.vol.java.client.ApiClient; + +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 + } +} +``` + +### Authentication +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.vol.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.vol.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 or redirection attempts + } +} +``` + +## Usage + +### Invoking an operation + +```java +import com.nutanix.vol.java.client.ApiClient; +import com.nutanix.vol.java.client.api.IscsiClientsApi; +import com.nutanix.dp1.vol.volumes.v4.config.GetIscsiClientApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + IscsiClientsApi iscsiClientsApi = new IscsiClientsApi(client); + String extId = "e75AFfAb-DbDE-3e3c-17fE-DCef543A8b3a"; + GetIscsiClientApiResponse getIscsiClientApiResponse = iscsiClientsApi.getIscsiClientById(extId); + } +} +``` + +### 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. + +```java +import com.nutanix.vol.java.client.ApiClient; + +public class Sample { + public void configureClient() { + ApiClient 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers. This would mean that the [ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header received in the response of a fetch (GET) operation should be used as an [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match) header for the modification (PUT) operation. +```java +import com.nutanix.vol.java.client.ApiClient; +import com.nutanix.dp1.vol.volumes.v4.config.GetIscsiClientApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + // perform GET call + IscsiClientsApi iscsiClientsApi = new IscsiClientsApi(client); + String extId = "e75AFfAb-DbDE-3e3c-17fE-DCef543A8b3a"; + GetIscsiClientApiResponse getIscsiClientApiResponse = iscsiClientsApi.getIscsiClientById(extId); + // Extract E-Tag Header + final String eTagHeader = ApiClient.getEtag(getIscsiClientApiResponse); + // ... + // Perform update call with received E-Tag reference + IscsiClient iscsiClient = (IscsiClient) getIscsiClientApiResponse.getData(); + // initialize/change parameters for update + HashMap opts = new HashMap<>(); + opts.put("If-Match", eTagHeader); + iscsiClientsApi.updateIscsiClientById(iscsiClientextId, , opts); + } +} + +``` + +### 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](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 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.vol.java.client.ApiClient; +import com.nutanix.vol.java.client.api.IscsiClientsApi; +import com.nutanix.dp1.vol.volumes.v4.config.ListIscsiClientsApiResponse; + +public class Sample { + public void performOperation() { + ApiClient client = new ApiClient(); + // Configure the client + // ... + IscsiClientsApi iscsiClientsApi = new IscsiClientsApi(client); + int page = 0; + int limit = 50; + String filter = null; + String orderby = null; + String expand = null; + String select = null; + ListIscsiClientsApiResponse listIscsiClientsApiResponse = iscsiClientsApi.listIscsiClients(page, limit, filter, orderby, expand, select); + } +} +``` + +The list of filterable and sortable fields with expansion keys can be found in the documentation [here](https://developers.nutanix.com/). + +## API Reference + +This library has a full set of [API Reference Documentation](https://developers.nutanix.com/sdk-reference?namespace=volumes&version=v4.2&language=java). This documentation is auto-generated, and the location may change. + +## 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:sdk@nutanix.com) \ No newline at end of file