feat: Allow specifying API version

JanEbbing · JanEbbing · commit a57b3d747e2b · 2025-02-20T17:01:32.000Z
diff --git a/deepl-java/src/main/java/com/deepl/api/DeepLApiVersion.java b/deepl-java/src/main/java/com/deepl/api/DeepLApiVersion.java
@@ -0,0 +1,20 @@
+package com.deepl.api;
+
+public enum DeepLApiVersion {
+  VERSION_1("v1"),
+  VERSION_2("v2");
+
+  /**
+   * How the version is represented in the URL string. Does not include any slashes (/). Example:
+   * "v2"
+   */
+  private final String urlRepresentation;
+
+  private DeepLApiVersion(String urlRepresentation) {
+    this.urlRepresentation = urlRepresentation;
+  }
+
+  public String toString() {
+    return this.urlRepresentation;
+  }
+}
diff --git a/deepl-java/src/main/java/com/deepl/api/DeepLClient.java b/deepl-java/src/main/java/com/deepl/api/DeepLClient.java
@@ -73,7 +73,9 @@ public List<WriteResult> rephraseText(
       throws InterruptedException, DeepLException {
     Iterable<KeyValuePair<String, String>> params =
         createWriteHttpParams(texts, targetLang, options);
-    HttpResponse response = httpClientWrapper.sendRequestWithBackoff("/v2/write/rephrase", params);
+    HttpResponse response =
+        httpClientWrapper.sendRequestWithBackoff(
+            String.format("/%s/write/rephrase", apiVersion), params);
     checkResponse(response, false, false);
     return jsonParser.parseWriteResult(response.getBody());
   }
diff --git a/deepl-java/src/main/java/com/deepl/api/DeepLClientOptions.java b/deepl-java/src/main/java/com/deepl/api/DeepLClientOptions.java
@@ -3,6 +3,26 @@
 // license that can be found in the LICENSE file.
 package com.deepl.api;
 
+import org.jetbrains.annotations.Nullable;
+
 /** {@inheritDoc} */
 @SuppressWarnings("deprecation")
-public class DeepLClientOptions extends TranslatorOptions {}
+public class DeepLClientOptions extends TranslatorOptions {
+  /**
+   * Set the version of the DeepL API to use. By default, this value is <code>
+   * DeepLApiVersion.VERSION_2</code> and the most recent DeepL API version is used. Note that older
+   * API versions like <code>DeepLApiVersion.VERSION_1</code> might not support all features of the
+   * more modern API (eg. document translation is v2-only), and that not all API subscriptions have
+   * access to one or the other API version. If in doubt, always use the most recent API version you
+   * have access to.
+   */
+  public DeepLClientOptions setApiVersion(DeepLApiVersion apiVersion) {
+    this.apiVersion = apiVersion;
+    return this;
+  }
+
+  /** Gets the current API version. */
+  public @Nullable DeepLApiVersion getApiVersion() {
+    return apiVersion;
+  }
+}
diff --git a/deepl-java/src/main/java/com/deepl/api/Translator.java b/deepl-java/src/main/java/com/deepl/api/Translator.java
@@ -26,6 +26,7 @@ public class Translator {
 
   protected final Parser jsonParser = new Parser();
   protected final HttpClientWrapper httpClientWrapper;
+  protected final DeepLApiVersion apiVersion;
 
   /**
    * Initializes a new Translator object using your Authentication Key.
@@ -44,6 +45,7 @@ public Translator(String authKey, TranslatorOptions options) throws IllegalArgum
     if (authKey == null || authKey.length() == 0) {
       throw new IllegalArgumentException("authKey must be a non-empty string");
     }
+    this.apiVersion = options.apiVersion;
     String serverUrl =
         (options.getServerUrl() != null)
             ? options.getServerUrl()
@@ -195,7 +197,9 @@ public List<TextResult> translateText(
       throws DeepLException, InterruptedException {
     Iterable<KeyValuePair<String, String>> params =
         createHttpParams(texts, sourceLang, targetLang, options);
-    HttpResponse response = httpClientWrapper.sendRequestWithBackoff("/v2/translate", params);
+    HttpResponse response =
+        httpClientWrapper.sendRequestWithBackoff(
+            String.format("/%s/translate", this.apiVersion), params);
     checkResponse(response, false, false);
     return jsonParser.parseTextResult(response.getBody());
   }
@@ -251,7 +255,8 @@ public List<TextResult> translateText(
    * @throws DeepLException If any error occurs while communicating with the DeepL API.
    */
   public Usage getUsage() throws DeepLException, InterruptedException {
-    HttpResponse response = httpClientWrapper.sendGetRequestWithBackoff("/v2/usage");
+    HttpResponse response =
+        httpClientWrapper.sendGetRequestWithBackoff(String.format("/%s/usage", apiVersion));
     checkResponse(response, false, false);
     return jsonParser.parseUsage(response.getBody());
   }
@@ -295,7 +300,9 @@ public List<Language> getLanguages(LanguageType languageType)
     if (languageType == LanguageType.Target) {
       params.add(new KeyValuePair<>("type", "target"));
     }
-    HttpResponse response = httpClientWrapper.sendRequestWithBackoff("/v2/languages", params);
+    HttpResponse response =
+        httpClientWrapper.sendRequestWithBackoff(
+            String.format("/%s/languages", apiVersion), params);
     checkResponse(response, false, false);
     return jsonParser.parseLanguages(response.getBody());
   }
@@ -312,7 +319,8 @@ public List<Language> getLanguages(LanguageType languageType)
   public List<GlossaryLanguagePair> getGlossaryLanguages()
       throws DeepLException, InterruptedException {
     HttpResponse response =
-        httpClientWrapper.sendGetRequestWithBackoff("/v2/glossary-language-pairs");
+        httpClientWrapper.sendGetRequestWithBackoff(
+            String.format("/%s/glossary-language-pairs", apiVersion));
     checkResponse(response, false, false);
     return jsonParser.parseGlossaryLanguageList(response.getBody());
   }
@@ -451,7 +459,7 @@ public DocumentHandle translateDocumentUpload(
     try (FileInputStream inputStream = new FileInputStream(inputFile)) {
       HttpResponse response =
           httpClientWrapper.uploadWithBackoff(
-              "/v2/document", params, inputFile.getName(), inputStream);
+              String.format("/%s/document", apiVersion), params, inputFile.getName(), inputStream);
       checkResponse(response, false, false);
       return jsonParser.parseDocumentHandle(response.getBody());
     }
@@ -495,7 +503,8 @@ public DocumentHandle translateDocumentUpload(
     Iterable<KeyValuePair<String, String>> params =
         createHttpParams(sourceLang, targetLang, options);
     HttpResponse response =
-        httpClientWrapper.uploadWithBackoff("/v2/document/", params, fileName, inputStream);
+        httpClientWrapper.uploadWithBackoff(
+            String.format("/%s/document/", apiVersion), params, fileName, inputStream);
     checkResponse(response, false, false);
     return jsonParser.parseDocumentHandle(response.getBody());
   }
@@ -525,7 +534,7 @@ public DocumentStatus translateDocumentStatus(DocumentHandle handle)
       throws DeepLException, InterruptedException {
     ArrayList<KeyValuePair<String, String>> params = new ArrayList<>();
     params.add(new KeyValuePair<>("document_key", handle.getDocumentKey()));
-    String relativeUrl = String.format("/v2/document/%s", handle.getDocumentId());
+    String relativeUrl = String.format("/%s/document/%s", apiVersion, handle.getDocumentId());
     HttpResponse response = httpClientWrapper.sendRequestWithBackoff(relativeUrl, params);
     checkResponse(response, false, false);
     return jsonParser.parseDocumentStatus(response.getBody());
@@ -599,7 +608,8 @@ public void translateDocumentDownload(DocumentHandle handle, OutputStream output
       throws DeepLException, IOException, InterruptedException {
     ArrayList<KeyValuePair<String, String>> params = new ArrayList<>();
     params.add(new KeyValuePair<>("document_key", handle.getDocumentKey()));
-    String relativeUrl = String.format("/v2/document/%s/result", handle.getDocumentId());
+    String relativeUrl =
+        String.format("/%s/document/%s/result", apiVersion, handle.getDocumentId());
     try (HttpResponseStream response = httpClientWrapper.downloadWithBackoff(relativeUrl, params)) {
       checkResponse(response);
       assert response.getBody() != null;
@@ -682,7 +692,7 @@ public GlossaryInfo createGlossaryFromCsv(
    * @throws DeepLException If any error occurs while communicating with the DeepL API.
    */
   public GlossaryInfo getGlossary(String glossaryId) throws DeepLException, InterruptedException {
-    String relativeUrl = String.format("/v2/glossaries/%s", glossaryId);
+    String relativeUrl = String.format("/%s/glossaries/%s", apiVersion, glossaryId);
     HttpResponse response = httpClientWrapper.sendGetRequestWithBackoff(relativeUrl);
     checkResponse(response, false, true);
     return jsonParser.parseGlossaryInfo(response.getBody());
@@ -698,7 +708,8 @@ public GlossaryInfo getGlossary(String glossaryId) throws DeepLException, Interr
    * @throws DeepLException If any error occurs while communicating with the DeepL API.
    */
   public List<GlossaryInfo> listGlossaries() throws DeepLException, InterruptedException {
-    HttpResponse response = httpClientWrapper.sendGetRequestWithBackoff("/v2/glossaries");
+    HttpResponse response =
+        httpClientWrapper.sendGetRequestWithBackoff(String.format("/%s/glossaries", apiVersion));
     checkResponse(response, false, false);
     return jsonParser.parseGlossaryInfoList(response.getBody());
   }
@@ -729,7 +740,7 @@ public GlossaryEntries getGlossaryEntries(GlossaryInfo glossary)
    */
   public GlossaryEntries getGlossaryEntries(String glossaryId)
       throws DeepLException, InterruptedException {
-    String relativeUrl = String.format("/v2/glossaries/%s/entries", glossaryId);
+    String relativeUrl = String.format("/%s/glossaries/%s/entries", apiVersion, glossaryId);
     HttpResponse response = httpClientWrapper.sendGetRequestWithBackoff(relativeUrl);
     checkResponse(response, false, true);
     return GlossaryEntries.fromTsv(response.getBody());
@@ -754,7 +765,7 @@ public void deleteGlossary(GlossaryInfo glossary) throws DeepLException, Interru
    * @throws DeepLException If any error occurs while communicating with the DeepL API.
    */
   public void deleteGlossary(String glossaryId) throws DeepLException, InterruptedException {
-    String relativeUrl = String.format("/v2/glossaries/%s", glossaryId);
+    String relativeUrl = String.format("/%s/glossaries/%s", apiVersion, glossaryId);
     HttpResponse response = httpClientWrapper.sendDeleteRequestWithBackoff(relativeUrl);
     checkResponse(response, false, true);
   }
@@ -954,7 +965,9 @@ private GlossaryInfo createGlossaryInternal(
     params.add(new KeyValuePair<>("target_lang", targetLang));
     params.add(new KeyValuePair<>("entries_format", entriesFormat));
     params.add(new KeyValuePair<>("entries", entries));
-    HttpResponse response = httpClientWrapper.sendRequestWithBackoff("/v2/glossaries", params);
+    HttpResponse response =
+        httpClientWrapper.sendRequestWithBackoff(
+            String.format("/%s/glossaries", apiVersion), params);
     checkResponse(response, false, false);
     return jsonParser.parseGlossaryInfo(response.getBody());
   }
diff --git a/deepl-java/src/main/java/com/deepl/api/TranslatorOptions.java b/deepl-java/src/main/java/com/deepl/api/TranslatorOptions.java
@@ -26,10 +26,13 @@ public class TranslatorOptions {
   @Nullable private String serverUrl = null;
   private boolean sendPlatformInfo = true;
   @Nullable private AppInfo appInfo = null;
+  @Nullable protected DeepLApiVersion apiVersion = null;
 
   /** @deprecated Use {@link DeepLClient} instead. */
   @Deprecated
-  public TranslatorOptions() {}
+  public TranslatorOptions() {
+    apiVersion = DeepLApiVersion.VERSION_2;
+  }
 
   /**
    * Set the maximum number of failed attempts that {@link Translator} will retry, per request. By
