Ktor 3.0.0-rc-1 Help

XHttpMethodOverride

The XHttpMethodOverride plugin enables the capability to tunnel HTTP verbs inside the X-HTTP-Method-Override header. This might be useful if your server API handles multiple HTTP verbs (GET, PUT, POST, DELETE, and so on), but the client can only use a limited set of verbs (for example, GET and POST) due to specific limitations. For instance, if the client sends a request with the X-Http-Method-Override header set to DELETE, Ktor will process this request using the delete route handler.

Add dependencies

To use XHttpMethodOverride, you need to include the ktor-server-method-override artifact in the build script:

implementation("io.ktor:ktor-server-method-override:$ktor_version")
implementation "io.ktor:ktor-server-method-override:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-method-override-jvm</artifactId> <version>${ktor_version}</version> </dependency>

Install XHttpMethodOverride

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

  • ... 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.methodoverride.* fun main() { embeddedServer(Netty, port = 8080) { install(XHttpMethodOverride) // ... }.start(wait = true) }
import io.ktor.server.application.* import io.ktor.server.plugins.methodoverride.* // ... fun Application.module() { install(XHttpMethodOverride) // ... }

Configure XHttpMethodOverride

By default, XHttpMethodOverride checks the X-Http-Method-Override header to determine the route that should handle the request. You can customize a header name using the headerName property.

Example

The HTTP request below uses the POST verb with the X-Http-Method-Override header set to DELETE:

POST http://0.0.0.0:8080/customer/3 X-Http-Method-Override: DELETE

To handle such requests using the delete route handler, you need to install XHttpMethodOverride:

package com.example import io.ktor.http.* import io.ktor.serialization.kotlinx.json.* import io.ktor.server.application.* import io.ktor.server.plugins.contentnegotiation.* import io.ktor.server.plugins.methodoverride.* import io.ktor.server.response.* import io.ktor.server.routing.* import kotlinx.serialization.* import kotlinx.serialization.json.* @Serializable data class Customer(val id: Int, val firstName: String, val lastName: String) fun Application.main() { val customerStorage = mutableListOf<Customer>() customerStorage.addAll( arrayOf( Customer(1, "Jane", "Smith"), Customer(2, "John", "Smith"), Customer(3, "Jet", "Brains") ) ) install(XHttpMethodOverride) install(ContentNegotiation) { json(Json) } routing { get("/customer/{id}") { val id = call.parameters["id"] val customer: Customer = customerStorage.find { it.id == id!!.toInt() }!! call.respond(customer) } delete("/customer/{id}") { val id = call.parameters["id"] customerStorage.removeIf { it.id == id!!.toInt() } call.respondText("Customer is removed", status = HttpStatusCode.NoContent) } } }

You can find the full example here: json-kotlinx-method-override.

Last modified: 02 April 2024