From d59f67c1719ce227ce4fe02c7f27be16b9104c32 Mon Sep 17 00:00:00 2001 From: cloudant-sdks-automation <71659186+cloudant-sdks-automation@users.noreply.github.com> Date: Mon, 6 Jul 2026 16:24:16 +0000 Subject: [PATCH] docs(generated): Gen 2 compatibility notes Generated SDK source code using: - Generator version 3.114.4 - Specification version 1.0.0-dev0.1.39 - Automation (cloudant-sdks) version d586e4c --- KNOWN_ISSUES.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 3 ++- 2 files changed, 56 insertions(+), 1 deletion(-) diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index ab4aed873..32c5f5162 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -2,6 +2,60 @@ ## All Cloudant SDKs +### Cloudant (Gen 2) Compatibility + +Cloudant Gen 2 is compatible with IAM authentication only. +The SDK authentication types `BASIC` and `COUCHDB_SESSION` do not work with Cloudant Gen 2 instances. + +Instances of Cloudant Gen 2 do not provide some configuration and monitoring APIs that were available in Gen 1. + +Migrating an application using this SDK from Cloudant Gen 1 to Cloudant Gen 2 requires either removing calls to these operations +or replacing them with alternatives. + +This table summarizes the SDK operations that are incompatible with Cloudant Gen 2 instances and the recommended replacement operations. + +| Gen 1 operation | Summary | Gen 1 Endpoint | API docs link | Replacement operation for Gen 2 | +|---|---|---|---|---| +| **Authentication and authorization** | | | | | +| `postApiKeys` | Generates API keys for apps or persons to enable database access | `POST /_api/v2/api_keys` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#postapikeys) | Use IAM authentication | +| `putCloudantSecurityConfiguration` | Modify only Cloudant related database permissions | `PUT /_api/v2/db/{db}/_security` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#putcloudantsecurity) | Use [database level IAM policies](https://cloud.ibm.com/docs/cloudant-gen2?topic=cloudant-gen2-managing-access-for-cloudant#database-level-iam-policies) | +| **Audit events configuration** | | | | | +`getActivityTrackerEvents` | Retrieve activity tracking events information | `GET /_api/v2/user/activity_tracker/events` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getactivitytrackerevents) | `management` events are always enabled, `data` events are not currently available in Gen 2 | +`postActivityTrackerEvents` | Modify activity tracking events configuration | `POST /_api/v2/user/activity_tracker/events` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#postactivitytrackerevents) | `management` events are always enabled, `data` events are not currently available in Gen 2 | +| **CORS configuration** | | | | | +| `getCorsInformation` | Retrieve CORS configuration information | `GET /_api/v2/user/config/cors` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcorsinformation) | Use the [Platform Services SDK](#using-the-platform-services-sdk) +| `putCorsConfiguration` | Modify CORS configuration | `PUT /_api/v2/user/config/cors` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#putcorsconfiguration) | Use the [Platform Services SDK](#using-the-platform-services-sdk) +| **Capacity configuration** | | | | | +| `getCapacityDatabasesInformation` | Retrieve maximum allowed database count | `GET /_api/v2/user/capacity/databases` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcapacitydatabasesinformation) | Use the [Platform Services SDK](#using-the-platform-services-sdk) +| `getCapacityThroughputInformation` | Retrieve provisioned throughput capacity information | `GET /_api/v2/user/capacity/throughput` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcapacitythroughputinformation) | Use the [Platform Services SDK](#using-the-platform-services-sdk) +| `putCapacityThroughputConfiguration` | Update the target provisioned throughput capacity | `PUT /_api/v2/user/capacity/throughput` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#putcapacitythroughputconfiguration) | Use the [Platform Services SDK](#using-the-platform-services-sdk) +| **Capacity monitoring** | | | | | +| `getCurrentDatabasesInformation` | Retrieve current database count | `GET /_api/v2/user/current/databases` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcurrentdatabasesinformation) | Use the length of the list returned from the `getAllDbs` operation. +| `getCurrentThroughputInformation` | Retrieve the current provisioned throughput capacity consumption | `GET /_api/v2/user/current/throughput` | [API docs link](https://cloud.ibm.com/apidocs/cloudant/cloudant-gen1?code=java#getcurrentthroughputinformation) | Use a Prometheus instant query with IBM Cloud Monitoring APIs. For example to get the capacity consumption rate over the last minute use a query like `rate(ibm_cloudant_permitted_operations_total[1m])`. See the [IBM Cloud Monitoring docs for an example](https://cloud.ibm.com/docs/monitoring?topic=monitoring-metrics_api#metrics-api-sample-prom). + +#### Using the Platform Services SDK + +Use the [IBM Cloud Platform Services Java SDK](https://github.com/IBM/platform-services-java-sdk) Resource Controller APIs to programmatically configure your Cloudant Gen 2 instance. + +Update the configuration values in the `parameters` mapping of key-value pairs. +Read the current values from the `extensions` mapping of key-value pairs. + +| Key path in `parameters` or `extensions` | Value description | +| --- | --- | +`dataservices.cloudant.capacity_units` | The provisioned throughput capacity of the instance in [units](https://cloud.ibm.com/docs/cloudant-gen2?topic=cloudant-gen2-usage-and-charges#provisioned-throughput-capacity-units) +`dataservices.cloudant.configuration.cors` | The CORS configuration object of the instance with booleans for `enabled` and `allowCredentials` and a string array of `origins` +`dataservices.cloudant.configuration.db_count_limit` | Read only value of the maximum number of databases allowed on the instance + +##### Viewing configuration + +Use [Get a resource instance](https://cloud.ibm.com/apidocs/resource-controller/resource-controller?code=java#get-resource-instance) to retrieve the resource instance configuration. + +##### Modifying configuration + +For a new instance use [Create (provision) a new resource instance](https://cloud.ibm.com/apidocs/resource-controller/resource-controller?code=java#create-resource-instance). +For a pre-existing instance use [Update a resource instance](https://cloud.ibm.com/apidocs/resource-controller/resource-controller?code=java#update-resource-instance). + + ### Path elements containing the `+` character Path elements containing the `+` character in the SDKs are not interoperable with: diff --git a/README.md b/README.md index 58d3d9b13..9f17c4371 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,8 @@ project: - Supported by IBM Cloudant. - Server compatibility with: - - IBM Cloudant. + - IBM Cloudant (Gen 1). + - IBM Cloudant (Gen 2) - see [compatibility notes](https://github.com/IBM/cloudant-java-sdk/tree/v0.10.19/KNOWN_ISSUES.md#cloudant-gen-2-compatibility). - [Apache CouchDB 3.x](https://docs.couchdb.org/en/stable/) for data operations. - Includes all the most popular and latest supported endpoints for applications.