Hexagon is a microservices toolkit written in Kotlin. Its purpose is to ease the building of services (Web applications, APIs or queue consumers) that run inside a cloud platform.

Programming language: Kotlin
License: MIT License
Latest version: v1.2.19

Hexagon alternatives and similar libraries

Based on the "REST Frameworks" category.
Alternatively, view hexagon alternatives based on common mentions on social networks and blogs.

  • Retrofit

    Type-safe REST client.
  • Dropwizard

    Opinionated framework for setting up modern web applications with Jetty, Jackson, Jersey and Metrics.
  • Scout APM uses tracing logic that ties bottlenecks to source code so you know the exact line of code causing performance issues and can get back to building a great product faster.
    Sponsored scoutapm.com
  • Spark

    Sinatra inspired framework.
  • Feign

    HTTP client binder inspired by Retrofit, JAXRS-2.0, and WebSocket.
  • rest.li

    Framework for building robust, scalable RESTful architectures using type-safe bindings and asynchronous, non-blocking IO with an end-to-end developer workflow that promotes clean practices, uniform interface design and consistent data modeling.
  • RESTEasy

    Fully certified and portable implementation of the JAX-RS specification.
  • Swagger

    Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.
  • Rapidoid

    A simple, secure and extremely fast framework consisting of embedded HTTP server, GUI components and dependency injection.
  • RestExpress

    Thin wrapper on the JBoss Netty HTTP stack to provide scaling and performance.
  • RAML

    Modeling language to generate REST APIs with contract first.
  • Microserver

    A convenient extensible Microservices plugin system for Spring & Spring Boot, with over 30 plugins and growing, that supports both micro-monolith and pure microservices styles.
  • Restlet Framework

    Pioneering framework with powerful routing and filtering capabilities, unified client and server API.
  • Jersey

    JAX-RS reference implementation.
  • RestX

    Framework based on annotation processing and compile-time source generation.
  • Crnk

    Implementation of the JSON API specification to build resource-oriented REST endpoints with sorting, filtering, paging, linking, object graphs, type-safety, bulk updates, integrations and more.
  • StubbornJava

    Unconventional Java code for building web servers / services without a framework. Think dropwizard but as a seed project instead of a framework. If this project had a theme it would be break the rules but be mindful of your decisions.
  • gemini

    Model Driven REST framework to automatically generate CRUD APIs
  • Restler

    Automatically generates a web service client at run time by analyzing its annotated Spring controller interface

Do you think we are missing an alternative of Hexagon or a related project?

Add another 'REST Frameworks' Library



The atoms of your platform

Home Site | Quick Start | Developer Guide

What is Hexagon

Hexagon is a microservices' toolkit (not a framework) written in Kotlin. Its purpose is to ease the building of server applications (Web applications, APIs or queue consumers) that run inside a cloud platform.

The Hexagon Toolkit provides several libraries to build server applications. These libraries provide single standalone features and are referred to as "Ports".

The main ports are:

  • The HTTP server: supports HTTPS, HTTP/2, mutual TLS, static files (serve and upload), forms processing, cookies, sessions, CORS and more.
  • The HTTP client: which supports mutual TLS, HTTP/2 and cookies among other things.

Each of these features or ports may have different implementations called "Adapters".

Hexagon is designed to fit in applications that conform to the [Hexagonal Architecture] (also called Clean Architecture or Ports and Adapters Architecture). Also, its design principles also fits in this architecture.

The Hexagon's goals and design principles are:

  • Put you in Charge: There is no code generation, no runtime annotation processing, no classpath based logic, and no implicit behaviour. You control your tools, not the other way around.

  • Modular: Each feature (Port) or adapter is isolated in its own module. Use only the modules you need without carrying unneeded dependencies.

  • Pluggable Adapters: Every Port may have many implementations (Adapters) using different technologies. You can swap adapters without changing the application code.

  • Batteries Included: It contains all the required pieces to make production-grade applications: settings management, serialization, dependency injection and build helpers.

  • Kotlin First: Take full advantage of Kotlin instead of just calling Java code from Kotlin. The library is coded in Kotlin for coding with Kotlin. No strings attached to Java (as a Language).

  • Properly Tested: The project's coverage is checked in every Pull Request. It is also stress-tested at TechEmpower Frameworks Benchmark.

For more information check the Quick Start Guide or the Developer Guide.

Simple HTTP service

You can clone a starter project (Gradle Starter or Maven Starter). Or you can create a project from scratch following these steps:

  1. Configure Kotlin in Gradle or Maven.
  2. Add the dependency:
  • In Gradle. Import it inside build.gradle:

    repositories {
  • In Maven. Declare the dependency in pom.xml:

  1. Write the code in the src/main/kotlin/Hello.kt file:
// hello
package com.hexagonkt.http.server.jetty

import com.hexagonkt.http.server.Server

lateinit var server: Server

fun main() {
    server = Server(JettyServletAdapter()) {
        get("/hello") {
            ok("Hello World!")

// hello
  1. Run the service and view the results at: http://localhost:2010/hello/world


Books Example

A simple CRUD example showing how to manage book resources. Here you can check the [full test](port_http_server/src/test/kotlin/examples/BooksTest.kt).

// books
data class Book(val author: String, val title: String)

private val books: MutableMap<Int, Book> = linkedMapOf(
    100 to Book("Miguel de Cervantes", "Don Quixote"),
    101 to Book("William Shakespeare", "Hamlet"),
    102 to Book("Homer", "The Odyssey")

val server: Server = Server(adapter) {
    post("/books") {
        // Require fails if parameter does not exists
        val author = queryParameters.require("author")
        val title = queryParameters.require("title")
        val id = (books.keys.max() ?: 0) + 1
        books += id to Book(author, title)
        send(201, id)

    get("/books/{id}") {
        val bookId = pathParameters.require("id").toInt()
        val book = books[bookId]
        if (book != null)
            // ok() is a shortcut to send(200)
            ok("Title: ${book.title}, Author: ${book.author}")
            send(404, "Book not found")

    put("/books/{id}") {
        val bookId = pathParameters.require("id").toInt()
        val book = books[bookId]
        if (book != null) {
            books += bookId to book.copy(
                author = queryParameters["author"] ?: book.author,
                title = queryParameters["title"] ?: book.title

            ok("Book with id '$bookId' updated")
        else {
            send(404, "Book not found")

    delete("/books/{id}") {
        val bookId = pathParameters.require("id").toInt()
        val book = books[bookId]
        books -= bookId
        if (book != null)
            ok("Book with id '$bookId' deleted")
            send(404, "Book not found")

    // Matches path's requests with *any* HTTP method as a fallback (return 404 instead 405)
    any("/books/{id}") { send(405) }

    get("/books") { ok(books.keys.joinToString(" ", transform = Int::toString)) }
// books

Session Example

Example showing how to use sessions. Here you can check the [full test](port_http_server/src/test/kotlin/examples/SessionTest.kt).

// session
val server: Server = Server(adapter) {
    path("/session") {
        get("/id") { ok(session.id ?: "null") }
        get("/access") { ok(session.lastAccessedTime?.toString() ?: "null") }
        get("/new") { ok(session.isNew()) }

        path("/inactive") {
            get { ok(session.maxInactiveInterval ?: "null") }

            put("/{time}") {
                session.maxInactiveInterval = pathParameters.require("time").toInt()

        get("/creation") { ok(session.creationTime ?: "null") }
        post("/invalidate") { session.invalidate() }

        path("/{key}") {
            put("/{value}") {
                session.set(pathParameters.require("key"), pathParameters.require("value"))

            get { ok(session.get(pathParameters.require("key")).toString()) }
            delete { session.remove(pathParameters.require("key")) }

        get {
            val attributes = session.attributes
            val attributeTexts = attributes.entries.map { it.key + " : " + it.value }

            response.headers["attributes"] = attributeTexts.joinToString(", ")
            response.headers["attribute values"] = attributes.values.joinToString(", ")
            response.headers["attribute names"] = attributes.keys.joinToString(", ")

            response.headers["creation"] = session.creationTime.toString()
            response.headers["id"] = session.id ?: ""
            response.headers["last access"] = session.lastAccessedTime.toString()

            response.status = 200
// session

Error Handling Example

Code to show how to handle callback exceptions and HTTP error codes. Here you can check the [full test](port_http_server/src/test/kotlin/examples/ErrorsTest.kt).

// errors
class CustomException : IllegalArgumentException()

val server: Server = Server(adapter) {
    error(UnsupportedOperationException::class) {
        response.headers["error"] = it.message ?: it.javaClass.name
        send(599, "Unsupported")

    error(IllegalArgumentException::class) {
        response.headers["runtimeError"] = it.message ?: it.javaClass.name
        send(598, "Runtime")

    // Catching `Exception` handles any unhandled exception before (it has to be the last)
    error(Exception::class) { send(500, "Root handler") }

    // It is possible to execute a handler upon a given status code before returning
    error(588) { send(578, "588 -> 578") }

    get("/exception") { throw UnsupportedOperationException("error message") }
    get("/baseException") { throw CustomException() }
    get("/unhandledException") { error("error message") }

    get("/halt") { halt("halted") }
    get("/588") { halt(588) }
// errors

Filters Example

This example shows how to add filters before and after route execution. Here you can check the [full test](port_http_server/src/test/kotlin/examples/FiltersTest.kt).

// filters
private val users: Map<String, String> = mapOf(
    "Turing" to "London",
    "Dijkstra" to "Rotterdam"

private val server: Server = Server(adapter) {
    before { attributes["start"] = nanoTime() }

    before("/protected/*") {
        val authorization = request.headers["Authorization"] ?: halt(401, "Unauthorized")
        val credentials = authorization.removePrefix("Basic ")
        val userPassword = String(Base64.getDecoder().decode(credentials)).split(":")

        // Parameters set in call attributes are accessible in other filters and routes
        attributes["username"] = userPassword[0]
        attributes["password"] = userPassword[1]

    // All matching filters are run in order unless call is halted
    before("/protected/*") {
        if(users[attributes["username"]] != attributes["password"])
            halt(403, "Forbidden")

    get("/protected/hi") { ok("Hello ${attributes["username"]}!") }

    // After filters are ran even if request was halted before
    after { response.headers["time"] = nanoTime() - attributes["start"] as Long }
// filters

Files Example

The following code shows how to serve resources and receive files. Here you can check the full test.

// files
private val server: Server = Server(adapter) {
    path("/static") {
        get("/files/*", Resource("assets")) // Serve `assets` resources on `/html/*`
        get("/resources/*", File(directory)) // Serve `test` folder on `/pub/*`

    get("/html/*", Resource("assets")) // Serve `assets` resources on `/html/*`
    get("/pub/*", File(directory)) // Serve `test` folder on `/pub/*`
    get(Resource("public")) // Serve `public` resources folder on `/*`

    post("/multipart") { ok(request.parts.keys.joinToString(":")) }

    post("/file") {
        val part = request.parts.values.first()
        val content = part.inputStream.reader().readText()

    post("/form") {
        fun serializeMap(map: Map<String, List<String>>): List<String> = listOf(
            map.map { "${it.key}:${it.value.joinToString(",")}}" }.joinToString("\n")

        val queryParams = serializeMap(queryParametersValues)
        val formParams = serializeMap(formParametersValues)

        response.headersValues["queryParams"] = queryParams
        response.headersValues["formParams"] = formParams
// files

You can check more sample projects and snippets at the examples page.


This project is supported by:


The toolkit is properly tested. This is the coverage report:


Performance is not the primary goal, but it is taken seriously. You can check performance numbers in the TechEmpower Web Framework Benchmarks.


If you like this project and want to support it, the easiest way is to give it a star :v:.

If you feel like you can do more. You can contribute to the project in different ways:

To know what issues are currently open and be aware of the next features you can check the Project Board and the Organization Board at GitHub.

You can ask any question, suggestion or complaint at the project's Slack channel. You can be up to date of project's news following @hexagon_kt on Twitter.

Thanks to all project's contributors!



The project is licensed under the [MIT License]. This license lets you use the source for free or commercial purposes as long as you provide attribution and don’t hold any project member liable.

*Note that all licence references and agreements mentioned in the Hexagon README section above are relevant to that project's source code only.