Ktor を使用して Kotlin で RESTful API を作成する方法
コード例: tutorial-server-restful-api
使用プラグイン: Routingルーティングは、サーバーアプリケーションにおいて着信リクエストを処理するためのコアとなるプラグインです。、Static Contentスタイルシート、スクリプト、画像などの静的コンテンツを配信する方法を学びます。、 Content NegotiationContentNegotiation プラグインには、主に2つの目的があります。クライアントとサーバー間でのメディアタイプのネゴシエーション、および特定の形式でのコンテンツのシリアライズ/デシリアライズです。、kotlinx.serialization
このチュートリアルでは、JSON データを生成する RESTful API の例を取り上げながら、Kotlin と Ktor を使用してバックエンドサービスを構築する方法を説明します。
前回のチュートリアルタスクマネージャーアプリケーションを構築しながら、KotlinとKtorによるルーティング、リクエスト処理、およびパラメーターの基本を学びます。では、バリデーション、エラーハンドリング、ユニットテストの基礎を紹介しました。今回はこれらのトピックを発展させ、タスクを管理するための RESTful サービスを作成します。
このチュートリアルで学べる内容は以下のとおりです:
- JSON シリアライゼーションを使用する RESTful サービスの作成
- Content NegotiationContentNegotiation プラグインには、主に2つの目的があります。クライアントとサーバー間でのメディアタイプのネゴシエーション、および特定の形式でのコンテンツのシリアライズ/デシリアライズです。(コンテンツネゴシエーション)のプロセスの理解
- Ktor 内での REST API 向けルート(Route)の定義
前提条件
このチュートリアルは単独で進めることも可能ですが、事前に前回のチュートリアルを完了して、リクエストの処理とレスポンスの生成タスクマネージャーアプリケーションを構築しながら、KotlinとKtorによるルーティング、リクエスト処理、およびパラメーターの基本を学びます。方法を学んでおくことを強くお勧めします。
IntelliJ IDEA のインストールを推奨しますが、お好みの別の IDE を使用しても構いません。
Hello RESTful Task Manager
このチュートリアルでは、既存のタスクマネージャーを RESTful サービスとして書き換えます。これを行うために、いくつかの Ktor プラグインプラグインは、シリアライゼーション、コンテンツエンコーディング、圧縮などの一般的な機能を提供します。を使用します。
既存のプロジェクトに手動で追加することもできますが、新しいプロジェクトを生成してから前回のチュートリアルのコードを段階的に追加していく方が簡単です。必要なコードは進めながら再度すべて提示されるため、手元に前回のプロジェクトを用意していなくても問題ありません。
プラグインを含む新しいプロジェクトを作成する
Ktor Project Generator にアクセスします。
Project artifact フィールドに、プロジェクトのアーティファクト名として com.example.ktor-rest-task-app を入力します。

プラグインのセクションで、Add ボタンをクリックして以下のプラグインを検索し、追加します:
- Content Negotiation
- kotlinx.serialization
- Static Content
プラグインを追加すると、プロジェクト設定の下にすべてのプラグインが表示されます。 
Download ボタンをクリックして、Ktor プロジェクトを生成・ダウンロードします。
スターターコードを追加する
Ktor プロジェクトの作成、オープン、実行のチュートリアルで説明したように、IntelliJ IDEA でプロジェクトを開きます。
src/main/kotlin に移動し、model というサブパッケージを作成します。
model パッケージ内に、新しい Task.kt ファイルを作成します。
Task.kt ファイルを開き、優先度を表す
enumとタスクを表すclassを追加します:kotlinpackage com.example.model import kotlinx.serialization.Serializable enum class Priority { Low, Medium, High, Vital } @Serializable data class Task( val name: String, val description: String, val priority: Priority )前回のチュートリアルでは、
Taskを HTML に変換するために拡張関数を使用しました。今回は、Taskクラスにkotlinx.serializationライブラリのSerializable型のアノテーションを付与しています。Routing.kt ファイルを開き、既存のコードを以下の実装に置き換えます:
kotlinpackage com.example import com.example.model.* import io.ktor.server.application.* import io.ktor.server.http.content.* import io.ktor.server.response.* import io.ktor.server.routing.* fun Application.configureRouting() { routing { staticResources("static", "static") get("/tasks") { call.respond( listOf( Task("cleaning", "Clean the house", Priority.Low), Task("gardening", "Mow the lawn", Priority.Medium), Task("shopping", "Buy the groceries", Priority.High), Task("painting", "Paint the fence", Priority.Medium) ) ) } } }前回のチュートリアルと同様に、URL
/tasksに対する GET リクエスト用のルートを作成しました。今回はタスクのリストを手動で変換する代わりに、単にそのリストを返しています。IntelliJ IDEA で実行ボタン (
) をクリックしてアプリケーションを起動します。
ブラウザで http://0.0.0.0:8080/tasks にアクセスします。以下のように、タスクリストの JSON 表現が表示されるはずです:

明らかに多くの処理が内部で自動的に行われています。実際にはどのような処理が起きているのでしょうか?
Content Negotiation の理解
ブラウザを介した Content Negotiation
プロジェクトを作成した際、Content NegotiationContentNegotiation プラグインには、主に2つの目的があります。クライアントとサーバー間でのメディアタイプのネゴシエーション、および特定の形式でのコンテンツのシリアライズ/デシリアライズです。 プラグインを含めました。このプラグインは、クライアントがレンダリングできるコンテンツの種類を確認し、それらを現在のサービスが提供可能なコンテンツタイプと照合します。これこそが、
HTTP では、クライアントは Accept ヘッダーを通じて自身がレンダリング可能なコンテンツタイプを伝達します。このヘッダーの値には、1 つ以上のコンテンツタイプが指定されます。上記のケースでは、ブラウザに組み込まれている開発者ツールを使用して、このヘッダーの値を確認できます。
以下の例を見てみましょう:
text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7*/* が含まれていることに注目してください。このヘッダーは、HTML、XML、または画像を受け入れることを示していますが、それ以外のあらゆるコンテンツタイプも受け入れることを意味します。
Content Negotiation プラグインは、ブラウザにデータを返送するためのフォーマットを見つける必要があります。プロジェクト内の生成されたコードを確認すると、src/main/kotlin 内に Serialization.kt というファイルがあり、以下のような内容が含まれています:
fun Application.configureSerialization() {
install(ContentNegotiation) {
json()
}
} このコードは ContentNegotiation プラグインをインストールし、さらに kotlinx.serialization プラグインの設定も行っています。これにより、クライアントからリクエストが送信された際、サーバーは JSON としてシリアライズされたオブジェクトを返すことができます。
ブラウザからのリクエストの場合、ContentNegotiation プラグインは JSON しか返せないことを認識しており、ブラウザ側は送られてきたあらゆるものを表示しようとします。そのため、リクエストは正常に処理されます。
JavaScript を介した Content Negotiation
これをシミュレートするために、src/main/resources/static 内の index.html ページを開き、デフォルトのコンテンツを以下の内容に置き換えます:
html<html> <head> <title>A Simple SPA For Tasks</title> <script type="application/javascript"> function fetchAndDisplayTasks() { fetchTasks() .then(tasks => displayTasks(tasks)) } function fetchTasks() { return fetch( "/tasks", { headers: { 'Accept': 'application/json' } } ).then(resp => resp.json()); } function displayTasks(tasks) { const tasksTableBody = document.getElementById("tasksTableBody") tasks.forEach(task => { const newRow = taskRow(task); tasksTableBody.appendChild(newRow); }); } function taskRow(task) { return tr([ td(task.name), td(task.description), td(task.priority) ]); } function tr(children) { const node = document.createElement("tr"); children.forEach(child => node.appendChild(child)); return node; } function td(text) { const node = document.createElement("td"); node.appendChild(document.createTextNode(text)); return node; } </script> </head> <body> <h1>Viewing Tasks Via JS</h1> <form action="javascript:fetchAndDisplayTasks()"> <input type="submit" value="View The Tasks"> </form> <table> <thead> <tr><th>Name</th><th>Description</th><th>Priority</th></tr> </thead> <tbody id="tasksTableBody"> </tbody> </table> </body> </html>このページには、HTML フォームと空のテーブルが含まれています。フォームを送信すると、JavaScript のイベントハンドラーが
Acceptヘッダーをapplication/jsonに設定して/tasksエンドポイントにリクエストを送信します。返されたデータはデシリアライズされ、HTML テーブルに追加されます。IntelliJ IDEA で再実行ボタン (
) をクリックしてアプリケーションを再起動します。
URL http://0.0.0.0:8080/static/index.html にアクセスします。 View The Tasks ボタンをクリックすると、データを取得できるはずです:

本番環境では、ブラウザに直接 JSON を表示することは通常ありません。代わりに、ブラウザで実行されている JavaScript コードがリクエストを行い、返されたデータを Single Page Application (SPA) の一部として表示します。通常、この種のアプリケーションは React、Angular、または Vue.js などのフレームワークを使用して記述されます。
GET ルートを追加する
Content Negotiation のプロセスを理解できたので、前回のチュートリアルタスクマネージャーアプリケーションを構築しながら、KotlinとKtorによるルーティング、リクエスト処理、およびパラメーターの基本を学びます。の機能を今回実装するサービスへ移行していきましょう。
タスクリポジトリの再利用
タスクのリポジトリは変更することなく再利用できるため、まずそれから始めます。
model パッケージ内に、新しい TaskRepository.kt ファイルを作成します。
TaskRepository.kt を開き、以下のコードを追加します:
kotlinpackage com.example.model object TaskRepository { private val tasks = mutableListOf( Task("cleaning", "Clean the house", Priority.Low), Task("gardening", "Mow the lawn", Priority.Medium), Task("shopping", "Buy the groceries", Priority.High), Task("painting", "Paint the fence", Priority.Medium) ) fun allTasks(): List<Task> = tasks fun tasksByPriority(priority: Priority) = tasks.filter { it.priority == priority } fun taskByName(name: String) = tasks.find { it.name.equals(name, ignoreCase = true) } fun addTask(task: Task) { if (taskByName(task.name) != null) { throw IllegalStateException("Cannot duplicate task names!") } tasks.add(task) } }
GET リクエスト用ルートの再利用
リポジトリを作成したので、GET リクエスト用のルートを実装できます。タスクを HTML に変換する処理を考慮する必要がなくなったため、前回のコードを簡素化できます:
src/main/kotlin 内の Routing.kt ファイルに移動します。
Application.configureRouting()関数内の/tasksルートのコードを、以下の実装で更新します:kotlinpackage com.example import com.example.model.Priority import com.example.model.TaskRepository import io.ktor.http.* import io.ktor.server.application.* import io.ktor.server.http.content.* import io.ktor.server.response.* import io.ktor.server.routing.* fun Application.configureRouting() { routing { staticResources("static", "static") //updated implementation route("/tasks") { get { val tasks = TaskRepository.allTasks() call.respond(tasks) } get("/byName/{taskName}") { val name = call.parameters["taskName"] if (name == null) { call.respond(HttpStatusCode.BadRequest) return@get } val task = TaskRepository.taskByName(name) if (task == null) { call.respond(HttpStatusCode.NotFound) return@get } call.respond(task) } get("/byPriority/{priority}") { val priorityAsText = call.parameters["priority"] if (priorityAsText == null) { call.respond(HttpStatusCode.BadRequest) return@get } try { val priority = Priority.valueOf(priorityAsText) val tasks = TaskRepository.tasksByPriority(priority) if (tasks.isEmpty()) { call.respond(HttpStatusCode.NotFound) return@get } call.respond(tasks) } catch (ex: IllegalArgumentException) { call.respond(HttpStatusCode.BadRequest) } } } } }これにより、サーバーは以下の GET リクエストに応答できるようになります:
/tasks: リポジトリ内のすべてのタスクを返します。/tasks/byName/{taskName}: 指定されたtaskNameでフィルタリングされたタスクを返します。/tasks/byPriority/{priority}: 指定されたpriorityでフィルタリングされたタスクを返します。
IntelliJ IDEA で再実行ボタン (
) をクリックしてアプリケーションを再起動します。
機能のテスト
ブラウザを使用する
これらのルートはブラウザでテストできます。たとえば、http://0.0.0.0:8080/tasks/byPriority/Medium にアクセスすると、優先度が Medium のすべてのタスクが JSON 形式で表示されます:

この種のリクエストは通常 JavaScript から行われることを考えると、より詳細なテストを行うことが望ましいです。これには、Postman などの専用ツールの使用が適しています。
Postman を使用する
Postman で、URL
http://0.0.0.0:8080/tasks/byPriority/Mediumを指定した新しい GET リクエストを作成します。Headers ペインで、Accept ヘッダーの値を
application/jsonに設定します。Send をクリックしてリクエストを送信し、レスポンスビューアーでレスポンスを確認します。

HTTP リクエストファイルを使用する
プロジェクトのルートディレクトリに、新しい REST Task Manager.http ファイルを作成します。
REST Task Manager.http ファイルを開き、以下の GET リクエストを追加します:
httpGET http://0.0.0.0:8080/tasks/byPriority/Medium Accept: application/jsonIntelliJ IDEA 内からリクエストを送信するには、リクエストの横にあるガターアイコン(
)をクリックします。
リクエストが実行され、Services ツールウィンドウに結果が表示されます:

IntelliJ IDEA Ultimate では、HTTP リクエストファイル(.http)を使用して同じ手順を実行できます。
POST リクエスト用ルートの追加
前回のチュートリアルでは、HTML フォームを介してタスクを作成しました。しかし、現在は RESTful サービスを構築しているため、その方法は不要です。代わりに kotlinx.serialization フレームワークを活用し、主要な処理の大半をこれに任せます。
src/main/kotlin 内の Routing.kt ファイルを開きます。
Application.configureRouting()関数に以下のように新しい POST ルートを追加します:kotlin//... fun Application.configureRouting() { routing { //... route("/tasks") { //... //add the following new route post { try { val task = call.receive<Task>() TaskRepository.addTask(task) call.respond(HttpStatusCode.Created) } catch (ex: IllegalStateException) { call.respond(HttpStatusCode.BadRequest) } catch (ex: SerializationException) { call.respond(HttpStatusCode.BadRequest) } } } } }以下の新しい import 文を追加します:
kotlin//... import com.example.model.Task import io.ktor.server.request.receive import kotlinx.serialization.SerializationException/tasksに POST リクエストが送信されると、kotlinx.serializationフレームワークを使用してリクエストボディがTaskオブジェクトに変換されます。これが成功すると、タスクがリポジトリに追加されます。デシリアライズ処理に失敗した場合はSerializationExceptionが処理され、タスクが重複していた場合はIllegalStateExceptionが処理されます。アプリケーションを再起動します。
Postman でこの機能をテストするには、URL
http://0.0.0.0:8080/tasksへの新しい POST リクエストを作成します。Body パネルで、新しいタスクを表す以下の JSON ドキュメントを追加します:
json{ "name": "cooking", "description": "Cook the dinner", "priority": "High" }
Send をクリックしてリクエストを送信します。
http://0.0.0.0:8080/tasks 宛てに GET リクエストを送信することで、タスクが追加されたことを確認できます。
IntelliJ IDEA Ultimate では、HTTP リクエストファイルに以下を追加することで同じ手順を実行できます:
http### POST http://0.0.0.0:8080/tasks Content-Type: application/json { "name": "cooking", "description": "Cook the dinner", "priority": "High" }
削除のサポートを追加する
サービスへの基本的な操作の追加はほぼ完了しました。これらは通常、CRUD(作成: Create、読み取り: Read、更新: Update、削除: Delete)操作としてまとめられます。ここでは削除(Delete)操作を実装します。
TaskRepository.kt ファイル内の
TaskRepositoryオブジェクトに、名前に基づいてタスクを削除する以下のメソッドを追加します:kotlinfun removeTask(name: String): Boolean { return tasks.removeIf { it.name == name } }Routing.kt ファイルを開き、DELETE リクエストを処理するエンドポイントを
routing()関数内に追加します:kotlinfun Application.configureRouting() { //... routing { route("/tasks") { //... //add the following function delete("/{taskName}") { val name = call.parameters["taskName"] if (name == null) { call.respond(HttpStatusCode.BadRequest) return@delete } if (TaskRepository.removeTask(name)) { call.respond(HttpStatusCode.NoContent) } else { call.respond(HttpStatusCode.NotFound) } } } } }アプリケーションを再起動します。
HTTP リクエストファイルに以下の DELETE リクエストを追加します:
http### DELETE http://0.0.0.0:8080/tasks/gardeningIntelliJ IDEA 内から DELETE リクエストを送信するには、リクエストの横にあるガターアイコン(
)をクリックします。
Services ツールウィンドウにレスポンスが表示されます:

Ktor Client を使用したユニットテストの作成
ここまではアプリケーションを手動でテストしてきましたが、すでにお気づきのとおり、この方法は時間がかかり拡張性がありません。代わりに、組み込みの client オブジェクトを使用して JSON の取得とデシリアライズを行う JUnit テスト特別なテストエンジンを使用してサーバーアプリケーションをテストする方法を学びます。を実装できます。
src/test/kotlin 内にある ServerTest.kt ファイルを開きます。
ServerTest.kt ファイルの内容を以下のように置き換えます:
kotlinpackage com.example import com.example.model.Priority import com.example.model.Task import io.ktor.client.call.* import io.ktor.client.plugins.contentnegotiation.* import io.ktor.client.request.* import io.ktor.http.* import io.ktor.serialization.kotlinx.json.* import io.ktor.server.testing.* import kotlin.test.* class ApplicationTest { @Test fun tasksCanBeFoundByPriority() = testApplication { configure() val client = createClient { install(ContentNegotiation) { json() } } val response = client.get("/tasks/byPriority/Medium") val results = response.body<List<Task>>() assertEquals(HttpStatusCode.OK, response.status) val expectedTaskNames = listOf("gardening", "painting") val actualTaskNames = results.map(Task::name) assertContentEquals(expectedTaskNames, actualTaskNames) } @Test fun invalidPriorityProduces400() = testApplication { configure() val response = client.get("/tasks/byPriority/Invalid") assertEquals(HttpStatusCode.BadRequest, response.status) } @Test fun unusedPriorityProduces404() = testApplication { configure() val response = client.get("/tasks/byPriority/Vital") assertEquals(HttpStatusCode.NotFound, response.status) } @Test fun newTasksCanBeAdded() = testApplication { configure() val client = createClient { install(ContentNegotiation) { json() } } val task = Task("swimming", "Go to the beach", Priority.Low) val response1 = client.post("/tasks") { header( HttpHeaders.ContentType, ContentType.Application.Json ) setBody(task) } assertEquals(HttpStatusCode.Created, response1.status) val response2 = client.get("/tasks") assertEquals(HttpStatusCode.OK, response2.status) val taskNames = response2 .body<List<Task>>() .map { it.name } assertContains(taskNames, "swimming") } }サーバー側で行ったのと同様に、Ktor client にも
ContentNegotiationおよびkotlinx.serializationプラグインをインストールする必要がある点に注意してください。build.gradle.kts ファイルに以下の依存関係を追加します:
kotlintestImplementation(ktorLibs.client.contentNegotiation)
JsonPath を使用したユニットテストの作成
Ktor クライアントまたは同様のライブラリを使用したサービスのテストは便利ですが、品質保証(QA)の観点からは欠点もあります。サーバーは JSON を直接処理していないため、JSON の構造についての前提が正しいかを完全に確信することはできません。
たとえば、以下のような想定ミスがあり得ます:
- 実際には
objectが使用されているのに、値がarrayに格納されていると思い込んでいる。 - 実際には
stringであるプロパティが、numberとして格納されていると思い込んでいる。 - 宣言順にはシリアライズされないにもかかわらず、宣言順にシリアライズされていると思い込んでいる。
サービスが複数のクライアントによって使用されることを意図している場合、JSON の構造に確信を持つことが極めて重要です。これを実現するために、Ktor Client を使用してサーバーからテキストを取得し、JSONPath ライブラリを使用してその内容を解析します。
gradle/libs.versions.toml ファイルを開き、JSONPath のバージョンとそのライブラリエイリアスを定義します:
toml[versions] json-path = "2.9.0" [libraries] json-path = { module = "com.jayway.jsonpath:json-path", version.ref = "json-path" }build.gradle.kts ファイルの
dependenciesブロックに JSONPath ライブラリを追加します:kotlintestImplementation(libs.json.path)src/test/kotlin フォルダーに移動し、新しい ApplicationJsonPathTest.kt ファイルを作成します。
ApplicationJsonPathTest.kt ファイルを開き、以下の内容を追加します:
kotlinpackage com.example import com.jayway.jsonpath.DocumentContext import com.jayway.jsonpath.JsonPath import io.ktor.client.* import com.example.model.Priority import io.ktor.client.request.* import io.ktor.client.statement.* import io.ktor.http.* import io.ktor.server.testing.* import kotlin.test.* class ApplicationJsonPathTest { @Test fun tasksCanBeFound() = testApplication { configure() val jsonDoc = client.getAsJsonPath("/tasks") val result: List<String> = jsonDoc.read("$[*].name") assertEquals("cleaning", result[0]) assertEquals("gardening", result[1]) assertEquals("shopping", result[2]) } @Test fun tasksCanBeFoundByPriority() = testApplication { configure() val priority = Priority.Medium val jsonDoc = client.getAsJsonPath("/tasks/byPriority/$priority") val result: List<String> = jsonDoc.read("$[?(@.priority == '$priority')].name") assertEquals(2, result.size) assertEquals("gardening", result[0]) assertEquals("painting", result[1]) } suspend fun HttpClient.getAsJsonPath(url: String): DocumentContext { val response = this.get(url) { accept(ContentType.Application.Json) } return JsonPath.parse(response.bodyAsText()) } }JsonPath のクエリは以下のように機能します:
$[*].nameは、「ドキュメントを配列として扱い、各エントリの name プロパティの値を返す」ことを意味します。$[?(@.priority == '$priority')].nameは、「配列内のエントリのうち、priority が指定された値と一致するすべてのエントリの name プロパティの値を返す」ことを意味します。
このようなクエリを使用することで、返される JSON に対する理解が正しいことを確認できます。コードのリファクタリングやサービスの再デプロイを行う際、現行のフレームワークでのデシリアライズを壊さないような変更であっても、シリアライゼーションの変更点が検出されます。これにより、自信を持って公開 API を再リリースできるようになります。
次のステップ
お疲れ様でした!これで、タスクマネージャーアプリケーション用の RESTful API サービスの作成が完了し、Ktor Client と JsonPath を使用したユニットテストの詳細について学びました。
API サービスを再利用して Web アプリケーションを構築する方法を学ぶには、次のチュートリアルKtor と Thymeleaf テンプレートを使用して、Kotlin で Web サイトを構築する方法を学びます。に進んでください。
