Skip to content

Commit 24165c1

Browse files
wenbinfwenbinf
committed
Initial commit
1 parent 4947a0f commit 24165c1

File tree

11 files changed

+511
-2
lines changed

11 files changed

+511
-2
lines changed

‎.gitattributes‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#
2+
# https://help.github.com/articles/dealing-with-line-endings/
3+
#
4+
# These are explicitly windows files and should use crlf
5+
*.bat text eol=crlf
6+

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,8 @@
11
*.class
22
*.log
3+
4+
# Ignore Gradle project-specific cache directory
5+
.gradle
6+
7+
# Ignore Gradle build output directory
8+
build

‎README.md‎

Lines changed: 113 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,113 @@
1-
# podcast-api-scala
2-
The Official Scala library for the Listen Notes Podcast API
1+
# Podcast API Scala Library
2+
3+
The Podcast API Scala library provides convenient access to the [Listen Notes Podcast API](https://www.listennotes.com/api/) from
4+
applications written in the Scala language.
5+
6+
Simple and no-nonsense podcast search & directory API. Search the meta data of all podcasts and episodes by people, places, or topics. It's the same API that powers [the best podcast search engine Listen Notes](https://www.listennotes.com/).
7+
8+
This repo is actually a demo app using [the podcast-api Java library](https://github.com/ListenNotes/podcast-api-java).
9+
You can find example Scala code in the README.md of this repo.
10+
11+
If you have any questions, please contact [hello@listennotes.com](hello@listennotes.com?subject=Questions+about+the+Scala+SDK+of+Listen+API)
12+
13+
<a href="https://www.listennotes.com/api/"><img src="https://raw.githubusercontent.com/ListenNotes/ListenApiDemo/master/web/src/powered_by_listennotes.png" width="300" />
14+
15+
16+
**Table of Contents**
17+
18+
19+
## Installation
20+
21+
You can install this library for JVM-based languages, including Java, Kotlin, Clojure, Scala, Groovy...
22+
23+
### Gradle users
24+
25+
Add this dependency to your project's build file:
26+
27+
```groovy
28+
implementation "com.listennotes:podcast-api:1.0.6"
29+
```
30+
31+
### Maven users
32+
33+
Add this dependency to your project's POM:
34+
35+
```xml
36+
<dependency>
37+
<groupId>com.listennotes</groupId>
38+
<artifactId>podcast-api</artifactId>
39+
<version>1.0.6</version>
40+
</dependency>
41+
```
42+
43+
## Usage
44+
45+
The library needs to be configured with your account's API key which is
46+
available in your [Listen API Dashboard](https://www.listennotes.com/api/dashboard/#apps). Set `apiKey` to its
47+
value:
48+
49+
```scala
50+
import com.listennotes.podcast_api.Client
51+
import com.listennotes.podcast_api.exception._
52+
53+
object App {
54+
def main(args: Array[String]): Unit = {
55+
// If apiKey is not set or an empty string, then we'll connect
56+
// to the api mock server, which returns fake data for testing
57+
val apiKey = scala.util.Properties.envOrElse("LISTEN_API_KEY", "")
58+
val client = new Client(apiKey)
59+
60+
// Parameters are passed via this HashMap
61+
// All parameters can be found at:
62+
// https://www.listennotes.com/api/docs/
63+
val parameters = new java.util.HashMap[String, String]
64+
parameters.put("q", "startup")
65+
parameters.put("type", "episode")
66+
parameters.put("sort_by_date", "1")
67+
68+
try {
69+
val response = client.search(parameters)
70+
71+
// response.toJSON() returns an org.json.JSONObject
72+
println(response.toJSON().toString(2))
73+
74+
println("\n=== Some stats of your account ===\n")
75+
println("Free Quota this month: " + response.getFreeQuota() + " requests")
76+
println("Usage this month: " + response.getUsage() + " requests")
77+
} catch {
78+
case e: AuthenticationException => println("Wrong API key")
79+
case e: RateLimitException => println("you are using FREE plan and you exceed the quota limit")
80+
}
81+
}
82+
}
83+
```
84+
85+
If `apiKey` is null or "", then we'll connect to a [mock server](https://www.listennotes.com/api/tutorials/#faq0) that returns fake data for testing purposes.
86+
87+
You can quickly run sample code using gradle:
88+
```shell
89+
# Use api mock server for test data
90+
./gradlew run
91+
92+
# Use production server for real data
93+
LISTEN_API_KEY=your-api-key-here ./gradlew run
94+
```
95+
96+
97+
### Handling exceptions
98+
99+
Unsuccessful requests raise exceptions. The class of the exception will reflect
100+
the sort of error that occurred.
101+
102+
| Exception Class | Description |
103+
| ------------- | ------------- |
104+
| AuthenticationException | wrong api key or your account is suspended |
105+
| ApiConnectionException | fail to connect to API servers |
106+
| InvalidRequestException | something wrong on your end (client side errors), e.g., missing required parameters |
107+
| RateLimitException | you are using FREE plan and you exceed the quota limit |
108+
| NotFoundException | endpoint not exist, or podcast / episode not exist |
109+
| ListenApiException | something wrong on our end (unexpected server errors) |
110+
111+
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).
112+
113+
And you can see some sample code [here](https://github.com/ListenNotes/podcast-api-scala/blob/main/app/src/main/scala/podcast/api/scala/demo/App.scala).

‎app/build.gradle‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
/*
2+
* This file was generated by the Gradle 'init' task.
3+
*
4+
* This generated file contains a sample Scala application project to get you started.
5+
* For more details take a look at the 'Building Java & JVM projects' chapter in the Gradle
6+
* User Manual available at https://docs.gradle.org/7.0/userguide/building_java_projects.html
7+
*/
8+
9+
plugins {
10+
// Apply the scala Plugin to add support for Scala.
11+
id 'scala'
12+
13+
// Apply the application plugin to add support for building a CLI application in Java.
14+
id 'application'
15+
}
16+
17+
repositories {
18+
// Use Maven Central for resolving dependencies.
19+
mavenCentral()
20+
}
21+
22+
dependencies {
23+
// Use Scala 2.13 in our library project
24+
implementation 'org.scala-lang:scala-library:2.13.3'
25+
26+
// This dependency is used by the application.
27+
implementation 'com.google.guava:guava:30.0-jre'
28+
29+
// Podcast API
30+
implementation "com.listennotes:podcast-api:1.0.6"
31+
32+
// Use Scalatest for testing our library
33+
testImplementation 'junit:junit:4.13.1'
34+
testImplementation 'org.scalatest:scalatest_2.13:3.2.3'
35+
testImplementation 'org.scalatestplus:junit-4-13_2.13:3.2.2.0'
36+
37+
// Need scala-xml at test runtime
38+
testRuntimeOnly 'org.scala-lang.modules:scala-xml_2.13:1.2.0'
39+
}
40+
41+
application {
42+
// Define the main class for the application.
43+
mainClass = 'podcast.api.scala.demo.App'
44+
}

‎app/src/main/scala/podcast/api/scala/demo/App.scala‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
/*
2+
* This Scala source file was generated by the Gradle 'init' task.
3+
*/
4+
package podcast.api.scala.demo
5+
6+
import com.listennotes.podcast_api.Client
7+
import com.listennotes.podcast_api.exception._
8+
9+
object App {
10+
def main(args: Array[String]): Unit = {
11+
// If apiKey is not set or an empty string, then we'll connect
12+
// to the api mock server, which returns fake data for testing
13+
val apiKey = scala.util.Properties.envOrElse("LISTEN_API_KEY", "")
14+
val client = new Client(apiKey)
15+
16+
// Parameters are passed via this HashMap
17+
// All parameters can be found at:
18+
// https://www.listennotes.com/api/docs/
19+
val parameters = new java.util.HashMap[String, String]
20+
parameters.put("q", "startup")
21+
parameters.put("type", "episode")
22+
parameters.put("sort_by_date", "1")
23+
24+
try {
25+
val response = client.search(parameters)
26+
27+
// response.toJSON() returns an org.json.JSONObject
28+
println(response.toJSON().toString(2))
29+
30+
println("\n=== Some stats of your account ===\n")
31+
println("Free Quota this month: " + response.getFreeQuota() + " requests")
32+
println("Usage this month: " + response.getUsage() + " requests")
33+
} catch {
34+
case e: AuthenticationException => println("Wrong API key")
35+
case e: RateLimitException => println("you are using FREE plan and you exceed the quota limit")
36+
}
37+
}
38+
}

‎app/src/test/scala/podcast/api/scala/demo/AppSuite.scala‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/*
2+
* This Scala Testsuite was generated by the Gradle 'init' task.
3+
*/
4+
package podcast.api.scala.demo
5+
6+
import org.scalatest.funsuite.AnyFunSuite
7+
import org.junit.runner.RunWith
8+
import org.scalatestplus.junit.JUnitRunner
9+
10+
@RunWith(classOf[JUnitRunner])
11+
class AppSuite extends AnyFunSuite {
12+
test("App has a greeting") {
13+
}
14+
}

‎gradle/wrapper/gradle-wrapper.jar‎

57.8 KB
Binary file not shown.

‎gradle/wrapper/gradle-wrapper.properties‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
distributionBase=GRADLE_USER_HOME
2+
distributionPath=wrapper/dists
3+
distributionUrl=https\://services.gradle.org/distributions/gradle-7.0-bin.zip
4+
zipStoreBase=GRADLE_USER_HOME
5+
zipStorePath=wrapper/dists

0 commit comments

Comments
 (0)