Add a constructor to Client class.

Author: wenbinf

README.md

@@ -22,7 +22,7 @@ If you have any questions, please contact [[email protected]](hello@listenno
 Add this dependency to your project's build file:
 
 ```groovy
-implementation "com.listennotes:podcast-api:1.0.4"
+implementation "com.listennotes:podcast-api:1.0.5"
 ```
 
 ### Maven users
@@ -33,19 +33,79 @@ Add this dependency to your project's POM:
 <dependency>
   <groupId>com.listennotes</groupId>
   <artifactId>podcast-api</artifactId>
-  <version>1.0.4</version>
+  <version>1.0.5</version>
 </dependency>
 ```
 
-## Development
+## Usage
+
+The library needs to be configured with your account's API key which is
+available in your [Listen API Dashboard](https://www.listennotes.com/api/dashboard/#apps). Set `apiKey` to its
+value:
+
+```java
+import java.util.HashMap;
+import org.json.JSONObject;
+import com.listennotes.podcast_api.Client;
+import com.listennotes.podcast_api.ApiResponse;
+import com.listennotes.podcast_api.exception.ListenApiException;
+
+public class PodcastApiExample {
+    public static void main(String[] args) {
+        try {
+          // If apiKey is null or "", then we'll use mock api for test data
+          String apiKey = System.getenv("LISTEN_API_KEY");
+          Client objClient = new Client(apiKey);
+
+          // All parameters can be found at
+          //    https://www.listennotes.com/api/docs/
+          HashMap<String, String> parameters = new HashMap<>();
+          parameters.put("q", "startup");
+          parameters.put("type", "podcast");
+
+          ApiResponse response = objClient.search(parameters);
+
+          // For successful response, you get a org.json.JSONObject
+          System.out.println(response.toJSON().toString(2));
+
+          // Some handy methods to get your account stats
+          System.out.println("\n=== Some Account Information ===\n");
+          System.out.println("Free Quota this month: " + response.getFreeQuota() + " requests");
+          System.out.println("Usage this month: " + response.getUsage() + " requests");
+          System.out.println("Next billing date: " + response.getNextBillingDate());
+        } catch (ListenApiException e) {
+          e.printStackTrace();
+        }
+    }
+}
+```
 
-```sh
-# Run sample app
-./gradlew run -q
+If `apiKey` is None, then we'll connect to a [mock server](https://www.listennotes.com/api/tutorials/#faq0) that returns fake data for testing purposes.
 
-# Run all unit tests
-./gradlew test
+You can quickly run sample code using gradle:
+```shell
+# Use api mock server for test data
+./gradlew run
 
-# Run a specific test case
-./gradlew test --tests ClientTest.testSearch
+# Use production server for real data
+LISTEN_API_KEY=your-api-key-here ./gradlew run
 ```
+
+
+### Handling exceptions
+
+Unsuccessful requests raise exceptions. The class of the exception will reflect
+the sort of error that occurred.
+
+| Exception Class  | Description |
+| ------------- | ------------- |
+|  AuthenticationException | wrong api key or your account is suspended  |
+| ApiConnectionException  | fail to connect to API servers  |
+| InvalidRequestException  | something wrong on your end (client side errors), e.g., missing required parameters  |
+| RateLimitException  | you are using FREE plan and you exceed the quota limit  |
+| NotFoundException  | endpoint not exist, or podcast / episode not exist  |
+| ListenApiException  | something wrong on our end (unexpected server errors)  |
+
+All exception classes can be found in [this folder](https://github.com/ListenNotes/podcast-api-java/tree/main/src/main/java/com/listennotes/podcast_api/exception).
+
+And you can see some sample code [here](https://github.com/ListenNotes/podcast-api-java/blob/main/src/main/java/com/listennotes/podcast_api/Sample.java).

gradle.properties

@@ -1,5 +1,5 @@
 GROUP_ID=com.listennotes
-VERSION_NAME=1.0.4
+VERSION_NAME=1.0.5
 
 POM_URL=https://github.com/ListenNotes/podcast-api-java
 POM_SCM_URL[email protected]:ListenNotes/podcast-api-java.git

src/main/java/com/listennotes/podcast_api/Client.java

@@ -19,6 +19,7 @@
 import java.net.MalformedURLException;
 import java.net.ProtocolException;
 
+
 public final class Client {
     public static final String BASE_URL_TEST = "https://listen-api-test.listennotes.com/api/v2";
     public static final String BASE_URL_PROD = "https://listen-api.listennotes.com/api/v2";
@@ -29,6 +30,14 @@ public final class Client {
     protected HttpURLConnection con;
     protected Map<String, String> requestParams;
 
+    public Client(String apiKey) {
+        this.apiKey = apiKey;
+    }
+
+    public Client() {
+        // No api key. Use api mock server.
+    }
+
     public ApiResponse submitPodcast(Map<String, String> mapParams) throws ListenApiException {
         return this.post("podcasts/submit", mapParams);
     }
@@ -124,18 +133,14 @@ public ApiResponse search(Map<String, String> mapParams) throws ListenApiExcepti
 
     protected String getUrl(String strPath) {
         String strUrl = BASE_URL_TEST;
-        if (this.apiKey.length() > 0) {
+        if (this.apiKey != null &&this.apiKey.length() > 0) {
             strUrl = BASE_URL_PROD;
         }
 
         strUrl = strUrl + "/" + strPath;
         return strUrl;
     }
 
-    public void setApiKey(String strKey) {
-        this.apiKey = strKey;
-    }
-
     public HttpURLConnection getConnection(String strUrl) throws ListenApiException {
         URL url;
         try {
@@ -151,7 +156,7 @@ public HttpURLConnection getConnection(String strUrl) throws ListenApiException
 
         con.setDoOutput(true);
         con.setRequestProperty("User-Agent", USER_AGENT);
-        if (this.apiKey.length() > 0) {
+        if (this.apiKey != null && this.apiKey.length() > 0) {
             con.setRequestProperty("X-ListenAPI-Key", this.apiKey);
         }
         con.setConnectTimeout(5000);

src/main/java/com/listennotes/podcast_api/Sample.java

@@ -1,15 +1,15 @@
 package com.listennotes.podcast_api;
 
 import com.listennotes.podcast_api.exception.*;
-import java.util.Map;
 import java.util.HashMap;
 
 public final class Sample {
     public static void main(String[] args) {
         try {
-            Client objClient = new Client();
+            String apiKey = System.getenv("LISTEN_API_KEY");
+            Client objClient = new Client(apiKey);
 
-            Map<String, String> parameters;
+            HashMap<String, String> parameters;
             ApiResponse response;
 
             parameters = new HashMap<>();

src/test/java/com/listennotes/podcast_api/ClientTest.java

@@ -19,7 +19,7 @@ public void testSetApiKey() throws Exception {
         assertEquals(null, con.getRequestProperty("X-ListenAPI-Key"));
 
         String strApiKey = "helloWorld";
-        client.setApiKey(strApiKey);
+        client = new Client(strApiKey);
         con = client.getConnection(client.getUrl("test"));
         assertEquals(con.getRequestProperty("X-ListenAPI-Key"), strApiKey);