ktor-backend

name: ktor-backend description: This skill should be used when creating Ktor server endpoints, BFF APIs, and backend services. Use for REST APIs, request validation, and server features.

When to Use

Use this skill when:

• Creating new Ktor server endpoints and routes
• Implementing REST APIs and BFF (Backend-for-Frontend) services
• Adding request validation with kotlinx.serialization
• Designing API versioning strategies
• Writing TestApplication integration tests
• Setting up OpenAPI/Swagger documentation
• Implementing authentication and authorization middleware
• Adding server features like CORS, compression, logging

Do NOT use this skill for:

• Client-side HTTP requests (use @kmp-api-services for Ktor Client and API service patterns)
• Compose UI implementation (use compose-screen skill)
• Shared business logic (use kmp-mobile-expert skill)
• Database schema design (this project uses PokéAPI, no database layer yet)

Mode Detection

MANDATORY - READ ENTIRE FILE: Before implementing Ktor endpoints, you MUST read endpoint-patterns.md (~180 lines) for complete routing, versioning, and validation patterns.

Do NOT load for OpenAPI/Swagger setup or server feature configuration (CORS, compression, logging) - those remain in main SKILL.md.

Related Skills

• @kmp-api-services: Client-side HTTP patterns with Ktor Client, DTOs, and repository integration
• @kmp-data-layer: Repository implementation with Either<RepoError, T> error boundaries
• @kmp-testing-patterns: Kotest and MockEngine patterns for API service testing
• @kmp-architecture: Module structure, vertical slicing, and feature boundaries
• @kmp-critical-patterns: Quick reference for 6 core patterns (ViewModel, Either, Testing, etc.)
• @kmp-domain: Domain models and data classes consumed by server endpoints
• @kmp-gradle: Gradle convention plugins and server build configuration
• @kmp-commands: CLI commands for server validation and testing

Decision Framework

Before implementing Ktor endpoints, ask yourself:

1. What HTTP method and route structure?

   • GET for reads → /api/v1/resources/{id}
   • POST for creates → /api/v1/resources with request body
   • PUT for updates → /api/v1/resources/{id} with request body
   • DELETE for deletes → /api/v1/resources/{id}
   • Use versioned routes (/api/v1/) for API stability

2. How should errors be handled?

   • Validation errors → 400 Bad Request with error details
   • Not found → 404 Not Found
   • Server errors → 500 Internal Server Error (log details, return generic message)
   • Use call.respond(HttpStatusCode.X, ErrorResponse(...))

3. What testing is needed?

   • Use testApplication { } for endpoint tests
   • Test success path + all error cases (validation, not found, server error)
   • Verify response serialization with @Serializable models
   • Run server tests: ./gradlew :server:test

Essential Workflows

Workflow 1: Create New REST Endpoint

MANDATORY: Read endpoint-patterns.md for complete details.

Quick steps:

1. Define @Serializable request/response models with sealed interfaces for success/error
2. Create nested route() blocks with version prefix (/api/v1)
3. Add parameter validation with toIntOrNull() and error responses
4. Write TestApplication integration tests
5. Validate with script: .agents/skills/ktor-backend/scripts/validate-endpoint.sh

See endpoint-patterns.md for full code examples and templates.

Workflow 2: Add API Versioning

MANDATORY: Read endpoint-patterns.md for complete versioning strategy.

Quick steps:

1. Route by version prefix (/api/v1, /api/v2)
2. Use version-specific sealed response types
3. Add deprecation headers to old versions

See endpoint-patterns.md for full implementation.

Workflow 3: Set Up OpenAPI Documentation

To add Swagger/OpenAPI documentation:

1. Add Ktor Swagger plugin to dependencies:

   // server/build.gradle.kts
   dependencies {
       implementation(libs.ktor.swagger)
   }
   

2. Configure Swagger plugin:

   fun Application.configureSwagger() {
       install(Swagger) {
           swagger {
               info {
                   title = "Pokédex API"
                   version = "1.0.0"
                   description = "Kotlin Multiplatform Pokédex Backend-for-Frontend API"
               }
               schemes listOf(Scheme.HTTP, Scheme.HTTPS)
           }
       }
   }
   
   routing {
       swaggerUI(path = "swagger", swaggerFile = "openapi.json")
   }
   

3. Access documentation at http://localhost:8080/swagger

Critical Guardrails

NEVER List

Best Practices

Quick Reference

Validation Commands

Ktor Routing Patterns

For complete endpoint templates: See endpoint-patterns.md

Cross-References

Reference Implementation

Current server setup:

• Application.kt - Basic Ktor server with Netty
• server/build.gradle.kts - Server build configuration

Examples to reference:

• Ktor routing: Application.kt shows basic route() and get() usage
• Serialization: Add ContentNegotiation plugin with kotlinx.serialization
• Testing: Use TestApplication for integration tests

Recommended Ktor Plugins