Greeter Microservice

This is a simple REST microservice to greet people.

Of course, this is rather a template than a useful microservice 🙂. It serves as a template to create a REST microservice using Micronaut (with Data Pesistence, Security, Consul service registration and discovery, JMX Management, OpenAPI/Swagger). It's written in Kotlin, edited with IntelliJ and Gitpod, built with Gradle (producing an executable fat jar, supporting Gradle's build scan, Researchgate's release plugin, and a dependency update checker). It's tested with JUnit 5 and versioned with git (with an unseful .gitignore). For logging, logback is used and Logstash JSON can be used for structured logging. For builds and deployment, Docker (i.e. Dockerfile, docker-compose.yml and an useful .dockerignore) can be used, which is well integrated into GitLab CI/CD (i.e. .gitlab-ci.yml; deploys Docker image on GitLab registry). There is also integration with Travis (i.e. .travis.yml), which deploys on Heroku (i.e. Procfile) and GitHub Releases.

Remarks

Gradle build scan

Please be aware that Gradle build scans are enabled by default. Deactivate it in settings.gradle if you do not agree to their terms of service.

git tags

If you fork this repository to create your own application from this template

• remove all Git tags (or use GitHub's "use this template" button)

# See https://stackoverflow.com/questions/44702757/how-to-remove-all-git-origin-and-local-tags
$ git tag -d $(git tag -l) && git fetch && git push origin --delete $(git tag -l) && git tag -d $(git tag -l)

• and reset your version to version=0.0.1-SNAPSHOT in gradle.properties

If you use the "Use this template" on GitHub, this is not needed.

HTTP API

OpenAPI / Swagger

There is an OpenAPI (former: Swagger) specification created, which is available at http://localhost:8080/swagger/greeter-microservice-0.1.yml, build/tmp/kapt3/classes/main/META-INF/swagger/ in the source directory and META-INF/swagger/ in the jar file. It can easily be pasted into the Swagger Editor which provides a live demo for Swagger UI, but also offers to create client libraries via OpenAPI Generator.

Add person

$ curl --location --request POST 'http://localhost:8080/persons/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Foo Bar"
}'

{
    "id": "3e266d3b-df74-4918-9d5d-22a5983e9dc2",
    "name": "Foo Bar"
}

Get person

$ curl --location --request GET 'http://localhost:8080/persons/3e266d3b-df74-4918-9d5d-22a5983e9dc2'

{
    "id": "3e266d3b-df74-4918-9d5d-22a5983e9dc2",
    "name": "Foo Bar"
}

gRPC API

For services that primarily handle RPC-style requests (in contrast to resource-orientated REST), gRPC might be a better approach.

Protocol buffer and Service definitions

*.proto files in src/main/proto/ describe the gRPC services and their protobuf.

Generation

./gradlew generateProto generates Java/Kotlin files from the service and protobuf definitions at src/main/proto/*.proto. They will be placed at build/generated/source/proto/main/ and contain classes for the messages and functions for the service rpcs.

Endpoint implementation

Implementing endpoints is quite simple and demonstrated in GreetingEndpoint.

List services

As gRPC server reflection is provided by the ReflectionFactory, grpcurl can list all available services:

$ ./grpcurl -plaintext localhost:50051 list
greeting.Greeting
grpc.reflection.v1alpha.ServerReflection

Call

A gRPC call can be made with:

$ ./grpcurl -plaintext -d '{"name":"Hans", "locale":"de_DE"}' localhost:50051 greeting.Greeting/Greet
{
  "message": "Grüß Gott, Hans"
}

Configuration

There is a application.yml included in the jar file. Its content can be modified and saved as a separate application.yml on the level of the jar file. Configuration can also be applied via the other supported ways of Micronaut (see https://docs.micronaut.io/latest/guide/index.html#config). For Docker, the configuration via environment variables is the most interesting one (see docker-compose.yml).