Pinboard Poster for Kotlin, Java and Android

A small library for posting to Pinboard.

Examples

Kotlin

val poster = PinboardPoster("user:TOKEN")

poster.addPin("https://example.com/foo", "This is a test")
poster.addPin("https://example.com", "This is a test", tags = arrayOf("foo", "bar"))
poster.deletePin("https://example.com/bar")

View Examples

Java

var poster = new PinboardClient("user:TOKEN");

poster.addPin("https://example.com/foo", "This is a test");

poster.addPin(
    new PinConfig.Builder("https://example.com", "This is a test")
        .tags("foo", "bar")
        .build()
);

poster.deletePin("https://example.com/bar");

View Examples

Your API authentication token is available on the Pinboard settings page.

bld

To use with bld, include the following dependency in your build file:

repositories = List.of(MAVEN_CENTRAL, CENTRAL_SNAPSHOTS);

scope(compile)
    .include(dependency("net.thauvin.erik:pinboard-poster:1.2.0"));

Be sure to use the bld Kotlin extension in your project.

View Example

Gradle, Maven, etc.

To install and run from Gradle, add the following to the build.gradle file:

repositories {
    mavenCentral()
}

dependencies {
    compile 'net.thauvin.erik:pinboard-poster:1.2.0'
}

View Examples

Instructions for using with Maven, Ivy, etc. can be found on Maven Central.

Adding

The addPin function support all of the Pinboard API parameters:

import java.time.ZonedDateTime

poster.addPin(
    url = "https://www.example.com",
    description = "This is the title",
    extended = "This is the extended description.",
    tags = arrayOf("tag1", "tag2", "tag3"),
    dt = ZonedDateTime.now(),
    replace = true,
    shared = true,
    toRead = false
)

url and description are required.

It returns true if the bookmark was added successfully, false otherwise.

Deleting

The deletePin function support all of the Pinboard API parameters:

poster.deletePin(url = "https://www.example.com/")

It returns true if the bookmark was deleted successfully, false otherwise.

Logging

The library used java.util.logging to log errors. Logging can be configured as follows:

Kotlin

with(poster.logger) {
    addHandler(ConsoleHandler().apply { level = Level.FINE })
    level = Level.FINE
    useParentHandlers = false
}

Java

final ConsoleHandler consoleHandler = new ConsoleHandler();
consoleHandler.setLevel(Level.FINE);
final Logger logger = poster.getLogger();
logger.addHandler(consoleHandler);
logger.setLevel(Level.FINE);
logger.setUseParentHandlers(false);

or using a logging properties file.

API Authentication Token

The token can also be located in a properties file or environment variable.

Local Property

For example, using the default PINBOARD_API_TOKEN key value from a local.properties file:

# local.properties
PINBOARD_API_TOKEN=user\:TOKEN

val poster = PinboardPoster(Paths.get("local.properties"))

or by specifying your own key:

# my.properties
my.api.key=user\:TOKEN

val poster = PinboardPoster(Paths.get("my.properties"), "my.api.key")

or even specifying your own property:

val p = Properties()
p.setProperty("api.key", "user:TOKEN")

val poster = PinboardPoster(p, "api.key")

In all cases, the value of the PINBOARD_API_TOKEN environment variable is used by default if the specified property is invalid or not found.

Environment Variable

If no arguments are passed to the constructor, the value of the PINBOARD_API_TOKEN environment variable will be used, if any.

export PINBOARD_API_TOKEN="user:TOKEN"

val poster = PinboardPoster()

API End Point

The API end point is automatically configured to https://api.pinboard.in/v1/. Since Pinboard uses the del.ico.us API, the library could potentially be used with another compatible service. To configure the API end point, use:

poster.apiEndPoint = "https://www.example.com/v1"

Contributing

See CONTIBUTING.md for information about contributing to this project.