Updated to use API v3.1, change base URL in EU, make region required (#…

…41) * Updated to use API v3.1 * Change base URL in EU * Make region required Co-authored-by: JakeBat <[email protected]> Co-authored-by: Ciaran Lawlor <[email protected]>
onfido · Apr 15, 2021 · 834022b · 834022b
1 parent 3ec213c
commit 834022b
Show file tree

Hide file tree

Showing 12 changed files with 112 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # Onfido Java Library
 
-The official Java library for integrating with the Onfido API.
+The official Java library for integrating with the Onfido API. Refer to the full [API documentation](https://documentation.onfido.com) for details of expected requests and responses for all resources.
 
-Documentation can be found at <https://documentation.onfido.com>
+This version uses Onfido API v3.1. Refer to our [API versioning guide](https://developers.onfido.com/guide/api-versioning-policy#client-libraries) for details of which client library versions use which versions of the API. 
 
 ## Installation
 
@@ -38,8 +38,7 @@ Instantiate and configure an `Onfido` instance with your API token, and region i
 ```java
 Onfido onfido = Onfido.builder()
                 .apiToken(System.getenv("ONFIDO_API_TOKEN"))
-                // Defaults to api.onfido.com, supports .regionUS() and .regionCA()
-                // .regionUS()
+                // Supports .regionEU, .regionUS() and .regionCA()
                 .build();
 ```
 

diff --git a/onfido-java/pom.xml b/onfido-java/pom.xml
@@ -4,7 +4,7 @@
 
     <groupId>com.onfido</groupId>
     <artifactId>onfido-api-java</artifactId>
-    <version>1.5.0</version>
+    <version>2.0.0</version>
 
     <name>Onfido API Java Client</name>
     <description>Official Java API client library for the Onfido API</description>

diff --git a/onfido-java/src/main/java/com/onfido/CheckManager.java b/onfido-java/src/main/java/com/onfido/CheckManager.java
@@ -2,6 +2,7 @@
 
 import com.onfido.api.ApiJson;
 import com.onfido.api.Config;
+import com.onfido.api.FileDownload;
 import com.onfido.api.ResourceManager;
 import com.onfido.exceptions.OnfidoException;
 import com.onfido.models.Check;
@@ -62,4 +63,15 @@ public List<Check> list(String applicantId) throws OnfidoException {
   public void resume(String checkId) throws OnfidoException {
     post(checkId + "/resume", "");
   }
+
+  /**
+   * Downloads a check.
+   *
+   * @param checkId the check id
+   * @return the downloaded file as a FileDownload
+   * @throws OnfidoException the onfido exception
+   */
+  public FileDownload download(String checkId) throws OnfidoException {
+    return downloadRequest(checkId + "/download");
+  }
 }
diff --git a/onfido-java/src/main/java/com/onfido/Onfido.java b/onfido-java/src/main/java/com/onfido/Onfido.java
@@ -8,9 +8,9 @@
 public final class Onfido {
   private static final OkHttpClient CLIENT = new OkHttpClient();
 
-  private static final String DEFAULT_API_URL = "https://api.onfido.com/v3/";
-  private static final String US_API_URL = "https://api.us.onfido.com/v3/";
-  private static final String CA_API_URL = "https://api.ca.onfido.com/v3/";
+  private static final String EU_API_URL = "https://api.eu.onfido.com/v3.1/";
+  private static final String US_API_URL = "https://api.us.onfido.com/v3.1/";
+  private static final String CA_API_URL = "https://api.ca.onfido.com/v3.1/";
 
   /** The Configuration for the instance. */
   public final Config config;
@@ -63,7 +63,7 @@ public static final class Builder {
     /** The Api token. */
     public String apiToken = "";
     /** The Api url. */
-    public String apiUrl = DEFAULT_API_URL;
+    public String apiUrl = "";
     /** The HTTP client interceptor. */
     private Interceptor clientInterceptor;
 
@@ -79,6 +79,14 @@ public Onfido build() {
         throw new RuntimeException("Please provide an apiToken");
       }
 
+      if (apiUrl == null || apiUrl.isEmpty()) {
+        throw new RuntimeException(
+          "Please specify a region with .regionEU(), .regionUS(), or .regionCA(). " +
+          "We previously defaulted to the EU region, so if you previously didn’t set a region or " +
+          "used api.onfido.com, please set your region using .regionEU()"
+        );
+      }
+
       return new Onfido(this);
     }
 
@@ -104,6 +112,16 @@ public Builder clientInterceptor(Interceptor interceptor) {
       return this;
     }
 
+    /**
+     * Sets the object to use the EU region base URL.
+     *
+     * @return the builder
+     */
+    public Builder regionEU() {
+      this.apiUrl = EU_API_URL;
+      return this;
+    }
+
     /**
      * Sets the object to use the US region base URL.
      *

diff --git a/onfido-java/src/main/java/com/onfido/api/ApiJson.java b/onfido-java/src/main/java/com/onfido/api/ApiJson.java
@@ -88,7 +88,9 @@ public JsonAdapter<?> create(Type type, Set<? extends Annotation> annotations, M
         public Object fromJson(JsonReader reader) throws IOException {
           Object value = adapter.fromJson(reader);
 
-          if (value instanceof List) {
+          if (value == null) {
+            return null;
+          } else if (value instanceof List) {
             return Collections.unmodifiableList((List<?>) value);
           } else {
             return Collections.unmodifiableMap((Map<?, ?>) value);

diff --git a/onfido-java/src/main/models/check.json b/onfido-java/src/main/models/check.json
@@ -100,8 +100,14 @@
     },
     "privacy_notices_read_consent_given": {
       "type": "boolean",
-      "writeOnly": true,
       "description": "Indicates that the privacy notices and terms of service have been read and, where specific laws require, that consent has been given for Onfido."
+    },
+    "webhook_ids": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Array of strings describing which webhooks to trigger for a check."
     }
   }
 }
diff --git a/onfido-java/src/test/java/com/onfido/JsonObject.java b/onfido-java/src/test/java/com/onfido/JsonObject.java
@@ -1,8 +1,10 @@
 package com.onfido;
 
 import com.squareup.moshi.JsonAdapter;
+import com.squareup.moshi.JsonWriter;
 import com.squareup.moshi.Moshi;
 import com.squareup.moshi.Types;
+import okio.Buffer;
 import java.io.IOException;
 import java.util.HashMap;
 import java.util.Map;
@@ -42,6 +44,18 @@ public Object get(String key) {
   }
 
   public String toJson() {
-    return ADAPTOR.toJson(map);
+    Buffer buffer = new Buffer();
+    JsonWriter jsonWriter = JsonWriter.of(buffer);
+
+    // Include null values in the generated JSON.
+    jsonWriter.setSerializeNulls(true);
+
+    try {
+      ADAPTOR.toJson(jsonWriter, map);
+    } catch (IOException e) {
+      throw new RuntimeException(e);
+    }
+
+    return buffer.readUtf8();
   }
 }
diff --git a/onfido-java/src/test/java/com/onfido/OnfidoTest.java b/onfido-java/src/test/java/com/onfido/OnfidoTest.java
@@ -7,23 +7,34 @@
 public class OnfidoTest {
   @Test(expectedExceptions = RuntimeException.class)
   public void throwsExceptionForMissingApiToken() {
-    Onfido.builder().build();
+    Onfido.builder().regionEU().build();
   }
 
   @Test(expectedExceptions = RuntimeException.class)
   public void throwsExceptionForNullApiToken() {
-    Onfido.builder().apiToken(null).build();
+    Onfido.builder().regionEU().apiToken(null).build();
+  }
+
+  @Test(expectedExceptions = RuntimeException.class)
+  public void throwsExceptionForMissingRegion() {
+    Onfido.builder().apiToken("token").build();
+  }
+
+  @Test()
+  public void usesEURegionApiUrl() {
+    Onfido onfido = Onfido.builder().apiToken("token").regionEU().build();
+    assertEquals("https://api.eu.onfido.com/v3.1/", onfido.config.getApiUrl());
   }
 
   @Test()
   public void usesUSRegionApiUrl() {
     Onfido onfido = Onfido.builder().apiToken("token").regionUS().build();
-    assertEquals("https://api.us.onfido.com/v3/", onfido.config.getApiUrl());
+    assertEquals("https://api.us.onfido.com/v3.1/", onfido.config.getApiUrl());
   }
 
   @Test()
   public void usesCanadaRegionApiUrl() {
     Onfido onfido = Onfido.builder().apiToken("token").regionCA().build();
-    assertEquals("https://api.ca.onfido.com/v3/", onfido.config.getApiUrl());
+    assertEquals("https://api.ca.onfido.com/v3.1/", onfido.config.getApiUrl());
   }
 }
diff --git a/onfido-java/src/test/java/com/onfido/integration/CheckManagerTest.java b/onfido-java/src/test/java/com/onfido/integration/CheckManagerTest.java
@@ -4,6 +4,7 @@
 
 import com.onfido.JsonObject;
 import com.onfido.Onfido;
+import com.onfido.api.FileDownload;
 import com.onfido.models.Check;
 import java.util.Arrays;
 import java.util.List;
@@ -15,7 +16,11 @@ public class CheckManagerTest extends ApiIntegrationTest {
 
   @Test
   public void createCheck() throws Exception {
-    String response = new JsonObject().add("applicant_id", "id").toJson();
+    String response =
+        new JsonObject()
+            .add("applicant_id", "id")
+            .add("webhook_ids", null)
+            .toJson();
 
     MockWebServer server = mockRequestResponse(response);
 
@@ -36,6 +41,7 @@ public void createCheck() throws Exception {
 
     // Correct response body
     assertEquals("id", check.getApplicantId());
+    assertEquals(null, check.getWebhookIds());
   }
 
   @Test
@@ -97,4 +103,22 @@ public void resumeCheck() throws Exception {
     RecordedRequest request = server.takeRequest();
     assertEquals("/checks/id/resume", request.getPath());
   }
+
+  @Test
+  public void downloadCheck() throws Exception {
+    MockWebServer server = mockFileRequestResponse("test", "application/pdf");
+
+    Onfido onfido =
+        Onfido.builder().apiToken("token").unknownApiUrl(server.url("/").toString()).build();
+
+    FileDownload download = onfido.check.download("check_id");
+
+    // Correct path
+    RecordedRequest request = server.takeRequest();
+    assertEquals("/checks/check_id/download", request.getPath());
+
+    // Correct response body
+    assertEquals("test", new String(download.content));
+    assertEquals("application/pdf", download.contentType);
+  }
 }
diff --git a/onfido-java/src/test/java/com/onfido/integration/DocumentManagerTest.java b/onfido-java/src/test/java/com/onfido/integration/DocumentManagerTest.java
@@ -63,11 +63,11 @@ public void downloadDocument() throws Exception {
     Onfido onfido =
         Onfido.builder().apiToken("token").unknownApiUrl(server.url("/").toString()).build();
 
-    FileDownload download = onfido.document.download("document id");
+    FileDownload download = onfido.document.download("document_id");
 
     // Correct path
     RecordedRequest request = server.takeRequest();
-    assertEquals("/documents/document%20id/download", request.getPath());
+    assertEquals("/documents/document_id/download", request.getPath());
 
     // Correct response body
     assertEquals("test", new String(download.content));

diff --git a/onfido-java/src/test/java/com/onfido/integration/LivePhotoManagerTest.java b/onfido-java/src/test/java/com/onfido/integration/LivePhotoManagerTest.java
@@ -54,11 +54,11 @@ public void downloadLivePhoto() throws Exception {
     Onfido onfido =
         Onfido.builder().apiToken("token").unknownApiUrl(server.url("/").toString()).build();
 
-    FileDownload download = onfido.livePhoto.download("live photo id");
+    FileDownload download = onfido.livePhoto.download("live_photo_id");
 
     // Correct path
     RecordedRequest request = server.takeRequest();
-    assertEquals("/live_photos/live%20photo%20id/download", request.getPath());
+    assertEquals("/live_photos/live_photo_id/download", request.getPath());
 
     // Correct response body
     assertEquals("test", new String(download.content));
@@ -73,7 +73,7 @@ public void downloadError() throws Exception {
         Onfido.builder().apiToken("token").unknownApiUrl(server.url("/").toString()).build();
 
     try {
-      onfido.livePhoto.download("live photo id");
+      onfido.livePhoto.download("live_photo_id");
       Assert.fail();
     } catch (ApiException ex) {
       Assert.assertEquals(403, ex.getStatusCode());

diff --git a/onfido-java/src/test/java/com/onfido/integration/LiveVideoManagerTest.java b/onfido-java/src/test/java/com/onfido/integration/LiveVideoManagerTest.java
@@ -23,11 +23,11 @@ public void downloadLiveVideo() throws Exception {
     Onfido onfido =
         Onfido.builder().apiToken("token").unknownApiUrl(server.url("/").toString()).build();
 
-    FileDownload download = onfido.liveVideo.download("live video id");
+    FileDownload download = onfido.liveVideo.download("live_video_id");
 
     // Correct path
     RecordedRequest request = server.takeRequest();
-    assertEquals("/live_videos/live%20video%20id/download", request.getPath());
+    assertEquals("/live_videos/live_video_id/download", request.getPath());
 
     // Correct response body
     assertEquals("test", new String(download.content));
@@ -41,11 +41,11 @@ public void downloadLiveVideoFrame() throws Exception {
     Onfido onfido =
         Onfido.builder().apiToken("token").unknownApiUrl(server.url("/").toString()).build();
 
-    FileDownload download = onfido.liveVideo.downloadFrame("live video id");
+    FileDownload download = onfido.liveVideo.downloadFrame("live_video_id");
 
     // Correct path
     RecordedRequest request = server.takeRequest();
-    assertEquals("/live_videos/live%20video%20id/frame", request.getPath());
+    assertEquals("/live_videos/live_video_id/frame", request.getPath());
 
     // Correct response body
     assertEquals("test", new String(download.content));