160 lines
5 KiB
Markdown
160 lines
5 KiB
Markdown
[](https://opensource.org/licenses/BSD-3-Clause)
|
|
[](https://kotlinlang.org/)
|
|
[](https://rife2.com/bld)
|
|
[](https://github.com/ethauvin/isgd-shorten/releases/latest)
|
|
[](https://central.sonatype.com/artifact/net.thauvin.erik/isgd-shorten)
|
|
[](https://oss.sonatype.org/content/repositories/snapshots/net/thauvin/erik/isgd-shorten/)
|
|
|
|
|
|
[](https://sonarcloud.io/dashboard?id=ethauvin_isgd-shorten)
|
|
[](https://github.com/ethauvin/isgd-shorten/actions/workflows/bld.yml)
|
|
[](https://circleci.com/gh/ethauvin/isgd-shorten/tree/master)
|
|
|
|
# [is.gd](https://is.gd/developers.php) Shortener for Kotlin, Java & Android
|
|
|
|
A simple implementation of the [is.gd](https://is.gd/) URL shortening and lookup [APIs](https://is.gd/developers.php).
|
|
|
|
## Examples (TL;DR)
|
|
|
|
```kotlin
|
|
import net.thauvin.erik.isgd.Isgd
|
|
|
|
...
|
|
|
|
Isgd.shorten("https://www.example.com/") // returns https://is.gd/Pt2sET
|
|
Isgd.lookup("https://is.gd/Pt2sET") // returns https://www.example.com
|
|
|
|
```
|
|
|
|
- View [bld](https://github.com/ethauvin/isgd-shorten/blob/master/examples/bld) or [Gradle](https://github.com/ethauvin/isgd-shorten/blob/master/examples/gradle) Examples.
|
|
|
|
### JSON or XML
|
|
|
|
The [is.gd API](https://is.gd/developers.php) can return data in plain text (default), JSON or XML.
|
|
|
|
```kotlin
|
|
Isgd.shorten("https://www.example.com/", format = Format.JSON)
|
|
```
|
|
|
|
returns:
|
|
|
|
```json
|
|
{ "shorturl": "https://is.gd/Pt2sET" }
|
|
```
|
|
|
|
### Parameters
|
|
|
|
All of the [is.gd API](https://is.gd/developers.php) parameters are supported:
|
|
|
|
```kotlin
|
|
Isgd.shorten(
|
|
url = url,
|
|
shorturl="foobar",
|
|
callback = "test",
|
|
logstats = true,
|
|
format = Format.JSON)
|
|
```
|
|
|
|
returns:
|
|
|
|
```js
|
|
test({ "shorturl": "https://is.gd/foobar" });
|
|
```
|
|
|
|
### bld
|
|
|
|
To use with [bld](https://rife2.com/bld), include the following dependency in your [build](https://github.com/ethauvin/isgd-shorten/blob/master/examples/bld/src/bld/java/com/example/ExampleBuild.java) file:
|
|
|
|
```java
|
|
repositories = List.of(MAVEN_CENTRAL, SONATYPE_SNAPSHOTS_LEGACY);
|
|
|
|
scope(compile)
|
|
.include("net.thauvin.erik:isgd-shorten:1.0.`");
|
|
```
|
|
|
|
### Gradle
|
|
|
|
To use with [Gradle](https://gradle.org/), include the following dependency in your [build](https://github.com/ethauvin/isgd-shorten/blob/master/examples/gradle/build.gradle.kts) file:
|
|
|
|
```gradle
|
|
repositories {
|
|
mavenCentral()
|
|
maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots") } // only needed for SNAPSHOT
|
|
}
|
|
|
|
dependencies {
|
|
implementation("net.thauvin.erik:isgd-shorten:1.0.1")
|
|
}
|
|
```
|
|
|
|
Instructions for using with Maven, Ivy, etc. can be found on [Maven Central](https://central.sonatype.com/artifact/net.thauvin.erik/isgd-shorten).
|
|
|
|
## Java
|
|
|
|
To make it easier to use the library with Java, configuration builders are available:
|
|
|
|
```java
|
|
var config = new Config.Builder()
|
|
.url("https://www.example.com/")
|
|
.shortUrl("foobar")
|
|
.callback("test")
|
|
.logStats(true)
|
|
.format(Format.JSON)
|
|
.build();
|
|
|
|
Isgd.shorten(config);
|
|
```
|
|
|
|
```java
|
|
var config = new Config.Builder()
|
|
.shortUrl("https://is.gd/Pt2sET")
|
|
.format(Format.XML)
|
|
.build();
|
|
|
|
Isgd.lookup(config);
|
|
```
|
|
|
|
### Errors
|
|
|
|
An `IsgdException` is thrown when an API error occurs. The error message (text, XML or JSON) and HTTP status code can be retrieved as follows:
|
|
|
|
```kotlin
|
|
try {
|
|
Isgd.shorten("https://is.gd/Pt2sET") // already shorten
|
|
} catch (e: IsgdException)
|
|
println("Status Code: ${e.statusCode}")
|
|
println("${e.message})
|
|
}
|
|
```
|
|
|
|
```console
|
|
Status Code: 400
|
|
Error: Sorry, the URL you entered is on our internal blacklist. It may have been used abusively in the past, or it may link to another URL redirection service.
|
|
```
|
|
|
|
### v.gd
|
|
|
|
Additionally, link can be shortened using [v.gd](https://v.gd/) by setting the `isVgd` flag:
|
|
|
|
```kotlin
|
|
Isgd.shorten("https://www.example.com/", isVgd = true) // returns https://v.gd/2z2ncj
|
|
```
|
|
|
|
## Contributing
|
|
|
|
If you want to contribute to this project, all you have to do is clone the GitHub
|
|
repository:
|
|
|
|
```console
|
|
git clone git@github.com:ethauvin/isgd-shorten.git
|
|
```
|
|
|
|
Then use [bld](https://rife2.com/bld) to build:
|
|
|
|
```console
|
|
cd isgd-shorten
|
|
./bld compile
|
|
```
|
|
|
|
The project has an [IntelliJ IDEA](https://www.jetbrains.com/idea/) project structure. You can just open it after all
|
|
the dependencies were downloaded and peruse the code.
|