From 03a12b8be823a693410db0fb664b2fac73eeb0a1 Mon Sep 17 00:00:00 2001 From: Sina Madani Date: Tue, 25 Jun 2024 15:06:28 +0100 Subject: [PATCH] Flesh out README --- README.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 123 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index adf9cb6..cd76b39 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,132 @@ [![Build Status](https://github.com/Vonage/vonage-kotlin-sdk/actions/workflows/build.yml/badge.svg)](https://github.com/Vonage/vonage-kotlin-sdk/actions/workflows/build.yml) [![codecov](https://codecov.io/gh/vonage/vonage-kotlin-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/vonage/vonage-kotlin-sdk) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md) -[![Snyk](https://snyk.io/test/github/vonage/vonage-java-sdk/badge.svg)](https://snyk.io/test/github/vonage/vonage-java-sdk) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE.txt) -This SDK provides syntactic sugar for the [Vonage Java Server SDK](https://github.com/Vonage/vonage-java-sdk) -to improve the user experience in Kotlin. It is therefore subject to the same requirements and capabilities. +This Kotlin SDK allows you to use [Vonage APIs](https://developer.vonage.com/api) in any JVM-based application. You'll need to have [created a Vonage account](https://dashboard.nexmo.com/sign-up?utm_source=DEV_REL&utm_medium=github&utm_campaign=java-client-library). +* [Supported APIs](#supported-apis) +* [Other SDKs](#other-sdks) +* [Installation](#installation) +* [Usage](#usage) +* [Configuration](#configuration) +* [FAQ](#frequently-asked-questions) +* [Contribute!](#contribute) +## Supported APIs +- [Messages](https://developer.vonage.com/en/messages/overview) +- [Verify](https://developer.vonage.com/en/verify/overview) + +## Other SDKs + +We also provide server SDKs in other languages: +- [Java](https://github.com/Vonage/vonage-java-sdk) +- [.NET](https://github.com/Vonage/vonage-dotnet-sdk) +- [PHP](https://github.com/Vonage/vonage-php-sdk) +- [Python](https://github.com/Vonage/vonage-python-sdk) +- [Ruby](https://github.com/Vonage/vonage-ruby-sdk) +- [NodeJS](https://github.com/Vonage/vonage-node-sdk) + +We also offer [client-side SDKs](https://developer.vonage.com/en/vonage-client-sdk/overview) for iOS, Android and JavaScript. +See all of our SDKs and integrations on the [Vonage Developer portal](https://developer.vonage.com/en/tools). + +## Installation + +Releases are published to [Maven Central](https://central.sonatype.com/artifact/com.vonage/kotlin-server-sdk). +Instructions for your build system can be found in the snippets section. +They're also available from [here](https://mvnrepository.com/artifact/com.vonage/kotlin-server-sdk/latest). +Release notes can be found in the [changelog](CHANGELOG.md). + +### Build It Yourself + +Alternatively you can clone the repo and build the JAR file yourself: + +```bash +git clone git@github.com:vonage/vonage-kotlin-sdk.git +mvn install +``` + +### Download everything in a ZIP file + +**Note**: We *strongly recommend* that you use a tool that supports dependency management, +such as [Maven](https://maven.apache.org/), [Gradle](https://gradle.org/) or [Ivy](http://ant.apache.org/ivy/). + +We provide a [ZIP file for each release](https://github.com/Vonage/vonage-kotlin-sdk/releases/), +containing the Java Server SDK JAR, along with all the dependencies. Download the file, unzip it, and add the JAR files +to your project's classpath. + +## Usage + +* For help understanding our APIs, check out our awesome [developer portal](https://developer.vonage.com/). +* Check the [Javadoc](https://www.javadoc.io/doc/com.vonage/kotlin-server-sdk/latest/index.html) for full reference documentation. +* There are also **many useful code samples** in our [Vonage/vonage-kotlin-code-snippets](https://github.com/Vonage/vonage-kotlin-code-snippets) repository. + +## Configuration + +## Typical Instantiation +For default configuration, you just need to specify your Vonage account credentials using API key and secret, private +key and application ID or both. For maximum compatibility with all APIs, it is recommended that you specify both +authentication methods, like so: + +```kotlin +import com.vonage.client.kt.Vonage + +val vonage = Vonage { + apiKey(API_KEY); apiSecret(API_SECRET) + applicationId(APPLICATION_ID) + privateKeyPath(PRIVATE_KEY_PATH) +} +``` + +You can also use environment variables for convenience, by setting the following: +- `VONAGE_API_KEY` +- `VONAGE_API_SECRET` +- `VONAGE_APPLICATION_ID` +- `VONAGE_PRIVATE_KEY_PATH` + +and then instantiate the client with: + +```kotlin +val vonage = Vonage { authFromEnv() } +``` + +### Customization +You can configure the base URI (for example, to do integration tests) and HTTP request timeout with `httpConfig` +during instantiation, like so: + +```kotlin +val vonageClient = Vonage { + authFromEnv() + httpConfig { + baseUri("http://localhost:8976") + timeoutMillis(15000) + } +} +``` + +## Frequently Asked Questions + +**Q: Why use this SDK instead of the [Vonage Java Server SDK](https://github.com/Vonage/vonage-java-sdk)?** + +**A:** This Kotlin SDK is actually based on the to improve the user experience in Kotlin. It adds +syntactic sugar, so you can avoid the cumbersome builder pattern in favour of a more idiomatic DSL-like +syntax. Furthermore, you are more partially shielded from "platform types" (the `!`) so you have a better +idea of what is and isn't nullable when creating requests. + +**Q: What is your policy on thread safety?** + +**A:** As with the Java Server SDK, only one thread should use the client at a time. +If you would like to use the SDK in a multithreaded environment, create a separate instance of +`Vonage` for each thread, or use a ThreadLocal instance. + +## Contribute! + +_We :heart: contributions to this library!_ + +It is a good idea to [talk to us](https://developer.vonage.com/community/slack) +first if you plan to add any new functionality. +Otherwise, [bug reports](https://github.com/Vonage/vonage-kotlin-sdk/issues), +[bug fixes](https://github.com/Vonage/vonage-kotlin-sdk/pulls) and feedback on the +library are always appreciated.