Caching headers

The CachingHeaders plugin (previously known as feature) adds the capability to configure the Cache-Control and Expires headers used for HTTP caching. You can introduce different caching strategies for specific content types, such as images, CSS and JavaScript files, and so on.

Install CachingHeaders

To install the CachingHeaders plugin, pass it to the install function in the application initialization code. Depending on the way used to create a server, this can be the embeddedServer function call ...

            import io.ktor.features.*
            // ...
            fun main() {
                embeddedServer(Netty, port = 8080) {
                    install(CachingHeaders)
                    // ...
                }.start(wait = true)
            }
        

... or a specified module.

            import io.ktor.features.*
            // ...
            fun Application.module() {
                install(CachingHeaders)
                // ...
            }
        

After installing CachingHeaders, you can configure caching settings for various content types.

Configure caching

To configure the CachingHeaders plugin, you need to define the options function to provide specified caching options for a given content type. The code snippet from the caching-headers example shows how to add the Cache-Control header with the max-age option for CSS:

    install(CachingHeaders) {
        options { outgoingContent ->
            when (outgoingContent.contentType?.withoutParameters()) {
                ContentType.Text.CSS -> CachingOptions(CacheControl.MaxAge(maxAgeSeconds = 3600))
                else -> null
            }
        }
    }

The CachingOptions object accepts Cache-Control and Expires header values as parameters:

The cacheControl parameter accepts a CacheControl value. You can use CacheControl.MaxAge to specify the max-age parameter and related settings, such as visibility, revalidation options, and so on. You can disable caching by using CacheControl.NoCache/CacheControl.NoStore.
The expires parameter allows you to specify the Expires header as a GMTDate or ZonedDateTime value.

Customize headers for specific routes

If you need to add caching headers for a specific route only, you can append the desired headers into a response. In this case, you don't need to install CachingHeaders. The code snippet below shows how to disable caching for the /profile route:

get("/profile") {
    call.response.headers.append(HttpHeaders.CacheControl, "no-cache, no-store")
    // ... 
}

You can learn more about routing in Ktor from Routing.

Last modified: 11 May 2022