DiscoveryDNS dnsapi-client

Introduction

This project is part of the DiscoveryDNS solution. It is a Java client to the DiscoveryDNS Server REST API.

User manual

The user manual of the DiscoveryDNS API can be found in this document.

DNSSEC Practice Statement

The DNSSEC Practice Statement of the DiscoveryDNS API can be found in this document.

API documentation

The details of the DiscoveryDNS REST API commands and responses can be found in this document.
If you want to develop a client to the API in a language different from Java, you will have to consult this document to find out what REST calls are to be implemented and what responses are to be expected.

License

This project is placed under the LGPLv3 license.

Download

The prefered way of using the client is via maven style dependency (which will automatically include required dependencies) as follows:

<dependency>
  <groupId>com.discoverydns.dnsapi</groupId>
  <artifactId>dnsapi-client</artifactId>
  <version>1.4.0</version>
</dependency>

Javadoc

The online version of the javadoc can be found here.

Usage

Examples are provided in the com.discoverydns.dnsapiclient.example package. However, here is a small description of what needs to be done:

The dnsapi-client library uses a DNSAPIClient to send commmands to the DNSAPI server, through a REST API over the HTTPS protocol.
The DNSAPIClient should be obtained from a DNSAPIClientFactory.
This DNSAPIClientFactory uses several feature providers to create the client:

An implementation of the DNSAPIClientConfig interface, to configure the HTTP connection used by the client.
An implementation of the SSLContextFactory interface, to create a javax.net.ssl.SSLContext instance, to establish a secure communication between the client and the server.
An implementation of the ObjectMapperFactory interface, to create an com.fasterxml.jackson.databind.ObjectMapper instance, for the client to serialize and deserialize the JSON data sent to or coming from the server.
An implementation of the ClientTransactionIdStrategy interface, to generate a client transaction id to be put in each transaction's meta-data.
An implementation of the TransactionLogHandler interface, to log the successful and failed transactions between the client and the server.

To obtain the DNSAPIClient from the DNSAPIClientFactory, you need to:

Setup the SLF4J logging (the client uses the logback's native binding) for log messages.
Instantiate the DNSAPIClientFactory.
Then, you can either:

Call its createInstance method, passing your custom implementation of all the features providers' interfaces described above.
Call its createInstanceFromDefaultProviders method to use the provided default implementation of all the features providers' interfaces. You then only need to pass:

An implementation of the DNSAPIClientConfig interface, to configure the HTTP connection used by the client.
An implementation of the DefaultSSLContextFactoryConfig interface, to configure the provided DefaultSSLContextFactory, using path-accessible keystore and if required, trustore resources (return null to the truststore path method will use the system truststore).
An implementation of the DefaultTransactionLogHandlerConfig interface, to configure the provided DefaultTransactionLogHandler, using path-accessible log file resources, with a rotation pattern.
A DefaultObjectMapperFactory will then be automatically provided, using the Jackson serializers and deserializers provided by the ddns-dnsjava library.
A DefaultClientTransactionIdStrategy will then be automatically provided, using random UUID strings as client transaction Ids.

Once the client is created, you can use it to send the commands to the server, thanks to its process method. The client is thread safe, and one client can be shared by many threads, however it can only execute one outstanding command per http connection configured.
Then simply follow the examples from the com.discoverydns.dnsapiclient.example package to see how to create and execute each command object.

Contribute

You can view the source on GitHub/DiscoveryDNS. Contributions via pull requests are welcome.