Update README.md

Author: wenbinf

Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "podcast-api"
-version = "0.1.0"
-authors = ["Cameron Fyfe <cameron.j.fyfe@gmail.com>"]
+version = "1.0.1"
+authors = ["Listen Notes, Inc. <hello@listennotes.com>"]
 edition = "2018"
 description = "Rust bindings for the Listen Notes Podcast API"
 license = "MIT"
-keywords = ["listennotes", "podcast"]
-documentation = "https://docs.rs/podcast-api"
+keywords = ["listennotes", "podcast", "searchengine", "podcastsearch"]
+documentation = "https://www.listennotes.com/api/docs/"
 repository = "https://github.com/ListenNotes/podcast-api-rust"
 readme = "README.md"
 

README.md

@@ -1,23 +1,111 @@
-# podcast-api-rust
-Rust library for the Listen Notes Podcast API
+# Podcast API Rust Library
 
-## Check
+The Podcast API Rust library provides convenient access to the [Listen Notes Podcast API](https://www.listennotes.com/api/) from
+applications written in the Rust language.
+
+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/).
+
+If you have any questions, please contact [[email protected]]([email protected]?subject=Questions+about+the+Rust+SDK+of+Listen+API)
+
+<a href="https://www.listennotes.com/api/"><img src="https://raw.githubusercontent.com/ListenNotes/ListenApiDemo/master/web/src/powered_by_listennotes.png" width="300" /></a>
+
+## Installation
+
+Add the following line to your `Cargo.toml` file's dependencies section:
+
+```toml
+[dependencies]
+podcast-api = "1.0.1"
+```
+
+## 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 `api_key` to its
+value:
+
+```rust
+use podcast_api::Error;
+use serde_json::json;
+
+#[tokio::main]
+async fn main() {
+    // Api Key  (None => Test API, Some(key) => Production API)
+    let api_key = None;
+    // let api_key = Some("put your api key here");    
+
+    // Create client
+    let client = podcast_api::Client::new(api_key);
+
+    // Call API
+    match client
+        .typeahead(&json!({
+            "q": "startup",
+            "show_podcasts": 1
+        }))
+        .await
+    {
+        Ok(response) => {
+            println!("Successfully called Listen Notes API.");
+            if let Ok(body) = response.json().await {
+                println!("Response Body:");
+                println!("{}", body);
+            } else {
+                println!("Response body JSON data parsing error.")
+            }
+        }
+        Err(err) => {
+            match err {
+                Error::NotFoundError => { println!("Not Found: {}", err); }
+                Error::AuthenticationError => { println!("Authentication Issue: {}", err); }
+                Error::RateLimitError => { println!("Rate Limit: {}", err); }
+                Error::InvalidRequestError => { println!("Invalid Request: {}", err); }
+                Error::ListenApiError => { println!("API Error: {}", err); }
+                Error::ApiConnectionError => { println!("Connection Issue: {}", err); }
+                Error::Reqwest(err) => { println!("Reqwest HTTP Client Error: {}", err); }
+                Error::Json(err) => { println!("JSON Parsing Error: {}", err); }
+            }
+        }
+    };
+}
+```
+
+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.
+
+
+### Handling errors
+
+Unsuccessful requests return errors.
+
+| Error  | Description |
+| ------------- | ------------- |
+|  AuthenticationError | wrong api key or your account is suspended  |
+| InvalidRequestError  | something wrong on your end (client side errors), e.g., missing required parameters  |
+| RateLimitError  | you are using FREE plan and you exceed the quota limit  |
+| NotFoundError  | endpoint not exist, or podcast / episode not exist  |
+| ApiConnectionError | failed to connect to Listen API servers | 
+| ListenApiError  | something wrong on our end (unexpected server errors)  |
+
+All errors can be found in [this file](https://github.com/ListenNotes/podcast-api-rust/blob/main/src/error.rs).
+
+
+## Development
+
+### Check
  - formatting: `cargo fmt -- --check`  
  - valid code: `cargo check`  
  - linting: `cargo clippy`  
 
-## Open Docs
+### Open Docs
 `cargo doc --open`
 
-## Build
+### Build
 `cargo build`  
 
-## Test
+### Test
 `cargo test`
 
-## Usage
-Add this to your `Cargo.toml`:
-```toml
-[dependencies]
-podcast-api = "0.1"
-```
+### Run example app
+```sh
+cd examples/sample && cargo run
+```

examples/sample/Cargo.toml

@@ -7,7 +7,7 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-podcast-api = { version = "^0", path = "../../" }
+podcast-api = { version = "^1.0.1", path = "../../" }
 reqwest = { version = "0.11", features = ["json"] }
 serde = { version = "1", features = ["derive"] } 
 serde_json = "1"

examples/sample/src/main.rs

@@ -5,6 +5,7 @@ use serde_json::json;
 async fn main() {
     // Api Key  (None => Test API, Some(key) => Production API)
     let api_key = None;
+    // let api_key = Some("put your api key here");    
 
     // Create client
     let client = podcast_api::Client::new(api_key);