From 3504d726510de497e38e546d3fbb8a703e70b8db Mon Sep 17 00:00:00 2001 From: Devesh-Skyflow Date: Wed, 20 May 2026 19:33:01 +0530 Subject: [PATCH 1/3] docs: add V2.1 migration guide and README upgrade banner MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds docs/migrate_to_v2.md covering auth options, client init, request/response structure, error format, and camelCase field name changes for V1 → V2 migration. Adds README banner pointing V1 users to the guide and noting EOL on 2026-10-31. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 3 + docs/migrate_to_v2.md | 252 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 255 insertions(+) create mode 100644 docs/migrate_to_v2.md diff --git a/README.md b/README.md index 647e8fe5..efc15e19 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,7 @@ # Skyflow Java + +> **Java V2.1.0 IS NOW AVAILABLE:** A new, improved version of the Skyflow SDK is ready with flexible authentication, multi-vault support, builder patterns, and richer error diagnostics. V1 is in maintenance mode (security patches only) and will reach End of Life on October 31, 2026. We recommend upgrading to v2.1.0 — see the **[Migration Guide](docs/migrate_to_v2.md)** for step-by-step instructions. + The Skyflow Java SDK is designed to help with integrating Skyflow into a Java backend. [![CI](https://img.shields.io/static/v1?label=CI&message=passing&color=green?style=plastic&logo=github)](https://github.com/skyflowapi/skyflow-java/actions) diff --git a/docs/migrate_to_v2.md b/docs/migrate_to_v2.md new file mode 100644 index 00000000..55facd45 --- /dev/null +++ b/docs/migrate_to_v2.md @@ -0,0 +1,252 @@ +# Skyflow Java SDK — V1 to V2 Migration Guide + +This guide covers the steps to migrate the Skyflow Java SDK from v1 to v2. + +--- + +## Authentication options + +In V2, multiple authentication options are available. You can now provide credentials in the following ways: + +- Environment variable (`SKYFLOW_CREDENTIALS`) _(Recommended)_ +- API Key +- Path to credentials JSON file +- Stringified JSON of credentials +- Bearer token + +**V1 (Old)** + +```java +static class DemoTokenProvider implements TokenProvider { + @Override + public String getBearerToken() throws Exception { + ResponseToken res = null; + try { + String filePath = ""; + res = Token.generateBearerToken(filePath); + } catch (SkyflowException e) { + e.printStackTrace(); + } + return res.getAccessToken(); + } +} +``` + +**V2 (New): Choose one of the following:** + +```java +// Option 1: API Key (Recommended) +Credentials skyflowCredentials = new Credentials(); +skyflowCredentials.setApiKey(""); + +// Option 2: Environment Variable (Recommended) +// Set SKYFLOW_CREDENTIALS in your environment + +// Option 3: Credentials File +skyflowCredentials.setPath(""); + +// Option 4: Stringified JSON +skyflowCredentials.setCredentialsString(""); + +// Option 5: Bearer Token +skyflowCredentials.setToken(""); +``` + +> **Notes:** +> - Use only ONE authentication method per credentials object. +> - API Key or environment variable are recommended for production. +> - For priority order see [Quickstart — Initialize the client](../README.md#initialize-the-client). + +--- + +## Initializing the client + +V2 introduces a builder pattern for client initialization with multi-vault support. + +**Key changes:** +- `vaultUrl` replaced with `clusterId` (derived from vault URL) +- Added `env` specification (e.g. `Env.PROD`, `Env.SANDBOX`) +- Log level is now per-client-instance + +**V1 (Old)** + +```java +DemoTokenProvider demoTokenProvider = new DemoTokenProvider(); +SkyflowConfiguration skyflowConfig = new SkyflowConfiguration( + "", "", demoTokenProvider +); +Skyflow skyflowClient = Skyflow.init(skyflowConfig); +``` + +**V2 (New)** + +```java +Credentials credentials = new Credentials(); +credentials.setPath(""); + +VaultConfig config = new VaultConfig(); +config.setVaultId(""); +config.setClusterId(""); +config.setEnv(Env.PROD); +config.setCredentials(credentials); + +Skyflow skyflowClient = Skyflow.builder() + .setLogLevel(LogLevel.DEBUG) + .addVaultConfig(config) + .build(); +``` + +--- + +## Request and response structure + +V2 removes third-party JSON objects in favour of native `ArrayList` and `HashMap` with a builder pattern for requests. + +**V1 (Old) — Request** + +```java +JSONObject recordsJson = new JSONObject(); +JSONArray recordsArrayJson = new JSONArray(); +JSONObject recordJson = new JSONObject(); +recordJson.put("table", "cards"); +JSONObject fieldsJson = new JSONObject(); +fieldsJson.put("cardNumber", "41111111111"); +fieldsJson.put("cvv", "123"); +recordJson.put("fields", fieldsJson); +recordsArrayJson.add(recordJson); +recordsJson.put("records", recordsArrayJson); +try { + JSONObject insertResponse = skyflowClient.insert(records); +} catch (SkyflowException e) { + System.out.println(e); +} +``` + +**V2 (New) — Request** + +```java +HashMap value = new HashMap<>(); +value.put("", ""); +value.put("", ""); +ArrayList> values = new ArrayList<>(); +values.add(value); + +InsertRequest insertRequest = InsertRequest.builder() + .table("") + .values(values) + .returnTokens(true) + .build(); + +InsertResponse response = skyflowClient.vault().insert(insertRequest); +``` + +**V1 (Old) — Response** + +```json +{ + "records": [ + { + "table": "cards", + "fields": { + "skyflow_id": "16419435-aa63-4823-aae7-19c6a2d6a19f", + "cardNumber": "f3907186-e7e2-466f-91e5-48e12c2bcbc1", + "cvv": "1989cb56-63da-4482-a2df-1f74cd0dd1a5" + } + } + ] +} +``` + +**V2 (New) — Response** + +```json +{ + "insertedFields": [ + { + "skyflowId": "9fac9201-7b8a-4446-93f8-5244e1213bd1", + "card_number": "5484-7829-1702-9110", + "cardholder_name": "b2308e2a-c1f5-469b-97b7-1f193159399b" + } + ], + "errors": null +} +``` + +--- + +## Request options + +V2 builder pattern replaces V1 options objects. + +**V1 (Old)** + +```java +InsertOptions insertOptions = new InsertOptions(true); +``` + +**V2 (New)** + +```java +InsertRequest request = InsertRequest.builder() + .table("") + .values(values) + .continueOnError(false) + .tokenMode(TokenMode.DISABLE) + .returnTokens(false) + .upsert("") + .build(); +``` + +--- + +## Error structure + +V2 provides richer error details for easier debugging. + +**V1 (Old)** + +```json +{ + "code": "", + "description": "" +} +``` + +**V2 (New)** + +```json +{ + "httpStatus": "", + "grpcCode": "", + "httpCode": "", + "message": "", + "requestId": "", + "details": ["
"] +} +``` + +--- + +## Credential field names (v2.1+) + +The credentials JSON file field names are updated to follow Java camelCase conventions. Both old and new forms are permanently accepted. + +| Old form (still accepted) | New form (preferred) | +|---|---| +| `clientID` | `clientId` | +| `keyID` | `keyId` | +| `tokenURI` | `tokenUri` | + +--- + +## Response field names (v2.1+) + +Response maps now return `skyflowId` (camelCase). The legacy `skyflow_id` key is still present for backward compatibility but is deprecated. + +| Deprecated (still returned) | Preferred | +|---|---| +| `skyflow_id` | `skyflowId` | + +--- + +For the full list of changes see [CHANGELOG.md](../CHANGELOG.md). From 0bd6d13caebd7efc978a50773102360eef972d94 Mon Sep 17 00:00:00 2001 From: Devesh-Skyflow Date: Thu, 21 May 2026 14:45:20 +0530 Subject: [PATCH 2/3] docs: update migration guide with v2.1 changes Add sections for UpdateRequest skyflowId preference, updateLogLevel and getBYOT deprecations. Co-Authored-By: Claude Sonnet 4.6 --- docs/migrate_to_v2.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/migrate_to_v2.md b/docs/migrate_to_v2.md index 55facd45..747076be 100644 --- a/docs/migrate_to_v2.md +++ b/docs/migrate_to_v2.md @@ -249,4 +249,35 @@ Response maps now return `skyflowId` (camelCase). The legacy `skyflow_id` key is --- +## Update request data key (v2.1+) + +When calling `update()`, use `skyflowId` (camelCase) as the key in the data map to identify the record. Using `skyflow_id` still works but emits a deprecation warning. If both keys are present, `skyflowId` takes precedence. + +```java +HashMap data = new HashMap<>(); +data.put("skyflowId", ""); // preferred +data.put("card_number", ""); + +UpdateRequest request = UpdateRequest.builder() + .table("") + .data(data) + .returnTokens(true) + .build(); + +skyflowClient.vault().update(request); +``` + +--- + +## Method renames (v2.1+) + +The following instance methods have been renamed for consistency. The old names still work but emit deprecation warnings. + +| Deprecated | Preferred | +|---|---| +| `skyflowClient.updateLogLevel(logLevel)` | `skyflowClient.setLogLevel(logLevel)` | +| `TokenMode.getBYOT()` | `TokenMode.getByot()` | + +--- + For the full list of changes see [CHANGELOG.md](../CHANGELOG.md). From 849ec4184a2d00b7c369322d8df7faa02bba3263 Mon Sep 17 00:00:00 2001 From: Devesh-Skyflow Date: Fri, 22 May 2026 13:01:07 +0530 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20add=20downloadURL=E2=86=92downloadU?= =?UTF-8?q?rl=20rename=20to=20migration=20guide=20method=20renames=20table?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 4.6 --- docs/migrate_to_v2.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/migrate_to_v2.md b/docs/migrate_to_v2.md index 747076be..671210fd 100644 --- a/docs/migrate_to_v2.md +++ b/docs/migrate_to_v2.md @@ -277,6 +277,7 @@ The following instance methods have been renamed for consistency. The old names |---|---| | `skyflowClient.updateLogLevel(logLevel)` | `skyflowClient.setLogLevel(logLevel)` | | `TokenMode.getBYOT()` | `TokenMode.getByot()` | +| `DetokenizeRequest.builder().downloadURL(b)` | `DetokenizeRequest.builder().downloadUrl(b)` | ---