README.md

\textcolor{#890000}{\text{THIS SDK IS IN DEVELOPMENT AND NOT READY FOR PRODUCTION USE YET!!!}}

About the FIT-Connect Java SDK

The Java SDK for FIT-Connect enables to build clients for senders and subscribers without directly interacting with any REST-Endpoints. It provides a simple fluent API that guides through the creation and sending of a submission, as well as receiving submissions as a subscriber.

For further information, check out the official docs: FIT-Connect Documentation as well as the:

• Self-Service-Portal (Testing Environment)
• FITKO project website

Outline

• About the FIT-Connect Java SDK
• Outline
• Getting Started
  • Build Dependencies
  • Prerequisites
  • Add FIT-Connect SDK to your build
• Modules
• Setup
• API Usage for Sender
  • Hand in already encrypted submission (e.g. from frontend)
    • 1. Retrieve public encryption key:
    • 2. Send encrypted data
  • Hand in a new submission with unencrypted data
• API Usage for Subscriber
  • Retrieving submissions
    • List with pagination
    • List without pagination
    • Receive single submission
  • Sending events to the event-log
    • Accepting a submission
    • Rejecting a submission
• Roadmap
• Contact
• License

Getting Started

How to set up the SDK project locally.

Build Dependencies

This section lists major frameworks/libraries used in the SDK.

• Java 11 (LTS)
• Maven 3.x
• Junit 5

Further 3rd party dependencies:

• Nimbus-Jose JWT
• Spring Web/HTTP
• Jackson FasterXMl
• JCommander
• Snakeyaml

Prerequisites

• Java Runtime >= 11, check your current setup in your commandline

  java --version 

(back to top)

Add FIT-Connect SDK to your build

To add a dependency on FIT-Connect using Maven, use the following:

<dependency>
  <groupId>dev.fitko.fitconnect.sdk</groupId>
  <artifactId>client</artifactId>
  <version>[Latest Version]</version>
</dependency>

With [Latest Version] of the last stable build or snapshot.

If you use a snapshot version, please add the maven snapshot repo to your pom.

<distributionManagement>
  <snapshotRepository>
  <id>ossrh</id>
  <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
  </snapshotRepository>
</distributionManagement>

(back to top)

Modules

See the projects' module documentation for more specific information:

• API Module
• Core Module
• Client Module

Setup

The following steps show how to get the SDK running

1. Create and account on the self service portal
2. Get your sender/subscriber API-key credentials
3. Clone the sdk repo

   git clone https://git.fitko.de/fit-connect/sdk-java

4. Build the project

   ./mvnw clean install -DskipTests

5. Enter your API keys and references to your private decryption key in config.yml
6. Provide config via environment variable FIT_CONNECT_CONFIG or load the config with

     var config = ApplicationConfigLoader.loadConfig("absolute/path/to/config.yml");
     var senderClient = ClientFactory.senderClient(config);

(back to top)

API Usage for Sender

The fluent API client for sender and subscriber allows method chaining to guide through all necessary steps and is called via dev.fitko.fitconnect.client.factory.ClientFactory.

Hand in already encrypted submission (e.g. from frontend)

If all data, metadata and attachments are encrypted outside the SDK the sender client allows to retrieve the public key for encryption as well as sending of already encrypted payloads.

For further information on how to implement end-2-end encryption please check the FIT-Connect documentation.

1. Retrieve public encryption key:

Optional<String> publicJwk =  ClientFactory.senderClient(config).getPublicKey(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"));

2. Send encrypted data

ClientFactory.senderClient(config)
        .newSubmissionWithEncryptedData("$encrpyt€ed d@t@")
        .withEncryptedAttachment(UUID.fromString("attachmentId"), "$encrpyt€ed @tt@chment")
        .withEncryptedJsonData("{$encrpyt€ed json}")
        .withEncryptedMetadata("$encrpyt€ed metadata")
        .withDestination(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"))
        .withServiceType("TestService", "Führerscheinbeantragung",  "urn:de:fim:leika:leistung:99400048079000")
        .submit();

Hand in a new submission with unencrypted data

If all data, metadata and attachments are encrypted in the sender using the SDK, the client automatically handles the encryption.

Be aware that this example is not end-2-end encrypted, see FIT-Connect documentation for details.

ClientFactory.senderClient(config)
        .newSubmission()
        .withAttachment(Path.of("path/to/attachment.txt").toFile()) // optional
        .withJsonData("{ \"foo\" : \"bar\"}")
        .withDestination(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"))
        .withServiceType("TestService", "Führerscheinbeantragung",  "urn:de:fim:leika:leistung:99400048079000")
        .submit();

API Usage for Subscriber

Retrieving submissions

Submissions can be fetched by id or as a list of submissions for a specific case.

List with pagination