Domino AppDev Pack meets Kotlin and Spring Boot

Domino AppDev Pack Java API is still quite fresh for me, but I always try to push the limits, so I've decided to add Kotlin  to the mix. If you've never heard of Kotlin, please go and check it. It's a pretty cool language that can run on JVM and allows you to write more readable code more easily. I'll build a simple CRUD REST API, running on Spring Boot, that works with Domino data.

Domino AppDev Pack series:

1. First Java API

2. Certificates

3. Kotlin REST API (this)

My original plan was to just try other APIs directly from Java, but Heiko Voigt has already done that in his presentation at CollabSphere 2020. The presentation is available here . If you want to know more about AppDev Pack, please watch it. You can also find the code in his github repo. I knew that C3UG had prepared a course about AppDev Pack, but I somehow missed their recent videos about Java APIs and 1.0.6 . It would have saved me a lot of time when I started to play with the Java domino-db API.

Few more words of warning. I've never used Kotlin before and I have not worked with Spring in the last 4 years. Actually, in the last year, I've written more C# code than Java, which will make my brain even more confused, so please use the code as an example, not a best practice - production-ready recommendation. I asked Martin Jinoch, who is a big fan of Kotlin, to do a quick review - he didn't tell me that the code is all wrong, so it should be ok. And it works too ...

Goal

The main goal of this post is to create a CRUD REST API that works with simple employee data - first name, last name, social security number. Since we are on Domino, we'll make the SSN encrypted. The API will have OpenAPI specification and we'll also serve Swagger UI.

IDE

When working with Kotlin, Intellij Idea is the best IDE you can choose. There are plugins/extensions for Eclipse and VS Code, but these can't match Idea. One of the reasons is that Kotlin and Idea are primarily developed by the same company - Jetbrains, so they try to make the experience as pleasant as possible. I've used Android Studio, which is based on Idea,  in past, so I knew a bit how to work with the IDE, but I was still surprised how easy it is to use. I use the Ultimate version that has excellent Spring support too.

 Getting started

If you are starting with a new Spring Boot project, the best way is to open spring initialize. It's also integrated into Idea, so you can launch it directly from the new project wizard too. You then just configure your environment - language, build tool, version, and Spring dependencies.

Then you can download the package, or if running directly in the IDE, get the project ready.

Dependencies

We will need few more dependencies

domino-db

As I've mentioned in my previous posts, domino-db is not available in public Maven repositories, so you'll either need to add it to yours or load it directly from the file system. I'm serving it from my Nexus server, so I just need to add

        <dependency>

            <groupId>com.hcl.domino</groupId>

            <artifactId>domino-db</artifactId>

            <version>1.0.0</version>

        </dependency>

springdoc-openapi-ui

springdoc-openapi java library helps automating the generation of API documentation using spring boot projects. springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.

        <dependency>

            <groupId>org.springdoc</groupId>

            <artifactId>springdoc-openapi-ui</artifactId>

            <version>1.4.8</version>

        </dependency>

That should be all we need for now.

domino-db infrastructure

In a normal Spring project, you'd probably use Spring Data project for your data-source. We don't have this luxury with Domino, so we need to manage the connection and queries manually. I've decided to create 2 beans - one for the executor service and one for the database.

You can see the details here https://github.com/mpradny/appdevpack-kotlin-rest/blob/master/src/main/kotlin/net/pristo/kotlin/proton/config/Domino.kt . In Kotin, it's encouraged to have multiple declarations, e.g. classes, in one file as long as they are closely related. I always struggled with this in C#, but I guess I'll get used to it here. This file contains full definition of structure in application properties and creations of these beans.

My configuration is:

Repository

Repositories are responsible for direct data manipulation in your data source. In my case it wraps the CRUD methods that are implemented using domino-db apis. For example the findAll method runs a simple DQL.

Usually, the most annoying part of data manipulation is mapping between raw data and data models or DTOs. I did it here using brute-force, but at least I've used a simple extension function that allowed me to create getItemValueString method that's not available in domino-db Document. It's a nice Koltin feature (and also in C#). 

That's basically all code that's needed for the read operation. 

REST API

Creating a REST API is super easy in Spring, so there is not much to write about.

Now we have a REST API and we can try to use it.

Other operations

Create, delete, and update operations are pretty straightforward too. Check the source code for the details

https://github.com/mpradny/appdevpack-kotlin-rest/blob/master/src/main/kotlin/net/pristo/kotlin/proton/rest/EmployeeResource.kt

Overall, I've written less than 200 lines of code (maybe even less than 100 as I don' have to count imports and fragments that were generated for me) and I have a working API. I like it. 

Encryption

The SSN item is being saved as encrypted. I'm not providing an encryption key, so it's just encrypted for the current technical user. It would be easy to add PublicEncryptionKeys field to the document and encrypt it using it. 

Error handling

One tricky part of domino-db module is error handling as usually all you get is 'Request failed' message. In many cases, you can dive deeper into the nested exceptions and in BulkOperationException find details for individual documents. In this code, I'm doing this on REST API level

During testing, I've seen that some operations don't return the unid, but it helps a lot with troubleshooting. E.g. if I don't provide password for my Notes ID - and I can't use encryption - during creation I get a nice message:

Conclusion

As always, the code is available in my github repo - https://github.com/mpradny/appdevpack-kotlin-rest

In the future, you may be able to use something like Project Keep to build APIs on top of Domino data, but it's not available yet.

I really like Kotlin. With my sloppy fingers, every character I type in my code is a potential typo and a bug, so when I can write less, I make fewer bugs. Working with IntelliJ Idea was also a nice experience, so I will continue to use it in the future.

Domino-db API so far works just fine, but I should also test the performance with some production-level load, not just single calls.