Conditional headers

The ConditionalHeaders plugin avoids sending the body of content if it has not changed since the last request. This is achieved by using the following headers:

The Last-Modified response header contains a resource modification time. For example, if the client request contains the If-Modified-Since value, Ktor will send a full response only if a resource has been modified after the given date. Note that for static files Ktor appends the Last-Modified header automatically after installing ConditionalHeaders.
The Etag response header is an identifier for a specific resource version. For instance, if the client request contains the If-None-Match value, Ktor won't send a full response in case this value matches the Etag. You can specify the Etag value when configuring ConditionalHeaders.

Add dependencies

To use ConditionalHeaders, you need to include the ktor-server-conditional-headers artifact in the build script:

implementation("io.ktor:ktor-server-conditional-headers:$ktor_version")

implementation "io.ktor:ktor-server-conditional-headers:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-server-conditional-headers-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Install ConditionalHeaders

To install the ConditionalHeaders plugin to the application, pass it to the install function in the specified module. The code snippets below show how to install ConditionalHeaders...

... inside the embeddedServer function call.
... inside the explicitly defined module, which is an extension function of the Application class.

                    import io.ktor.server.engine.*
                    import io.ktor.server.netty.*
                    import io.ktor.server.application.*
                    import io.ktor.server.plugins.conditionalheaders.*

                    fun main() {
                        embeddedServer(Netty, port = 8080) {
                            install(ConditionalHeaders)
                            // ...
                        }.start(wait = true)
                    }
                

                    import io.ktor.server.application.*
                    import io.ktor.server.plugins.conditionalheaders.*
                    // ...
                    fun Application.module() {
                        install(ConditionalHeaders)
                        // ...
                    }
                

The ConditionalHeaders plugin can also be installed to specific routes. This might be useful if you need different ConditionalHeaders configurations for different application resources.

Configure headers

To configure ConditionalHeaders, you need to call the version function inside the install block. This function provides access to a list of resource versions for a given ApplicationCall and OutgoingContent. You can specify the required versions by using the EntityTagVersion and LastModifiedVersion class objects.

The code snippet below shows how to add a Etag and Last-Modified headers for CSS:

    install(ConditionalHeaders) {
        val file = File("src/main/kotlin/com/example/Application.kt")
        version { call, outgoingContent ->
            when (outgoingContent.contentType?.withoutParameters()) {
                ContentType.Text.CSS -> listOf(
                    EntityTagVersion(file.lastModified().hashCode().toString()),
                    LastModifiedVersion(Date(file.lastModified()))
                )
                else -> emptyList()
            }
        }
    }

You can find the full example here: conditional-headers.

20 October 2025