From a57b3d747e2b18f567795f9d8263a088c957ac51 Mon Sep 17 00:00:00 2001 From: Jan Ebbing Date: Fri, 14 Feb 2025 17:33:38 +0000 Subject: [PATCH] feat: Allow specifying API version --- .../java/com/deepl/api/DeepLApiVersion.java | 20 ++++++++++ .../main/java/com/deepl/api/DeepLClient.java | 4 +- .../com/deepl/api/DeepLClientOptions.java | 22 ++++++++++- .../main/java/com/deepl/api/Translator.java | 39 ++++++++++++------- .../java/com/deepl/api/TranslatorOptions.java | 5 ++- 5 files changed, 74 insertions(+), 16 deletions(-) create mode 100644 deepl-java/src/main/java/com/deepl/api/DeepLApiVersion.java diff --git a/deepl-java/src/main/java/com/deepl/api/DeepLApiVersion.java b/deepl-java/src/main/java/com/deepl/api/DeepLApiVersion.java new file mode 100644 index 0000000..5725fbb --- /dev/null +++ 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 index ea7a74b..9d4b825 100644 --- 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 rephraseText( throws InterruptedException, DeepLException { Iterable> 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 index 46eafc8..1f2a6b3 100644 --- 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 + * DeepLApiVersion.VERSION_2 and the most recent DeepL API version is used. Note that older + * API versions like DeepLApiVersion.VERSION_1 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 index bb80a24..6df6b1a 100644 --- 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 translateText( throws DeepLException, InterruptedException { Iterable> 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 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 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 getLanguages(LanguageType languageType) public List 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> 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> 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> 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 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 index 1e7a21f..42f4634 100644 --- 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