본문으로 건너뛰기

🌐 REST API

📖 REST API란?​

REST API는 HTTP 메서드(GET, POST, PUT, DELETE)를 사용해 자원을 관리하는 웹 API입니다. 표준화된 방식으로 클라이언트와 서버가 통신합니다!

💡 HTTP 메서드​

CRUD 매핑​

GET    /users     - 목록 조회 (Read)
GET    /users/1   - 단건 조회 (Read)
POST   /users     - 생성 (Create)
PUT    /users/1   - 수정 (Update)
DELETE /users/1   - 삭제 (Delete)

🎯 완전한 CRUD API​

데이터 모델​

import kotlinx.serialization.Serializable

@Serializable
data class Todo(
    val id: Int,
    val title: String,
    val completed: Boolean = false
)

@Serializable
data class CreateTodoRequest(
    val title: String
)

@Serializable
data class UpdateTodoRequest(
    val title: String?,
    val completed: Boolean?
)

전체 구현​

import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import io.ktor.http.*
import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.plugins.contentnegotiation.*

fun Application.todoAPI() {
    install(ContentNegotiation) {
        json()
    }

    val todos = mutableListOf<Todo>()
    var nextId = 1

    routing {
        route("/todos") {
            // 목록 조회
            get {
                call.respond(todos)
            }

            // 단건 조회
            get("/{id}") {
                val id = call.parameters["id"]?.toIntOrNull()
                val todo = todos.find { it.id == id }

                if (todo != null) {
                    call.respond(todo)
                } else {
                    call.respond(HttpStatusCode.NotFound, mapOf("error" to "Todo를 찾을 수 없습니다"))
                }
            }

            // 생성
            post {
                val request = call.receive<CreateTodoRequest>()
                val todo = Todo(
                    id = nextId++,
                    title = request.title
                )
                todos.add(todo)

                call.respond(HttpStatusCode.Created, todo)
            }

            // 수정
            put("/{id}") {
                val id = call.parameters["id"]?.toIntOrNull()
                val request = call.receive<UpdateTodoRequest>()

                val index = todos.indexOfFirst { it.id == id }
                if (index == -1) {
                    call.respond(HttpStatusCode.NotFound, mapOf("error" to "Todo를 찾을 수 없습니다"))
                    return@put
                }

                val todo = todos[index]
                val updated = todo.copy(
                    title = request.title ?: todo.title,
                    completed = request.completed ?: todo.completed
                )
                todos[index] = updated

                call.respond(updated)
            }

            // 삭제
            delete("/{id}") {
                val id = call.parameters["id"]?.toIntOrNull()
                val removed = todos.removeIf { it.id == id }

                if (removed) {
                    call.respond(HttpStatusCode.NoContent)
                } else {
                    call.respond(HttpStatusCode.NotFound, mapOf("error" to "Todo를 찾을 수 없습니다"))
                }
            }
        }
    }
}

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

🎨 테스트하기​

cURL 예제​

# 생성
curl -X POST http://localhost:8080/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "Kotlin 공부하기"}'

# 목록 조회
curl http://localhost:8080/todos

# 단건 조회
curl http://localhost:8080/todos/1

# 수정
curl -X PUT http://localhost:8080/todos/1 \
  -H "Content-Type: application/json" \
  -d '{"completed": true}'

# 삭제
curl -X DELETE http://localhost:8080/todos/1

🔧 검증과 에러 처리​

요청 검증​

@Serializable
data class CreateUserRequest(
    val name: String,
    val email: String,
    val age: Int
)

post("/users") {
    val request = call.receive<CreateUserRequest>()

    // 검증
    when {
        request.name.isBlank() -> {
            call.respond(
                HttpStatusCode.BadRequest,
                mapOf("error" to "이름은 필수입니다")
            )
            return@post
        }
        !request.email.contains("@") -> {
            call.respond(
                HttpStatusCode.BadRequest,
                mapOf("error" to "유효하지 않은 이메일입니다")
            )
            return@post
        }
        request.age < 0 -> {
            call.respond(
                HttpStatusCode.BadRequest,
                mapOf("error" to "나이는 0 이상이어야 합니다")
            )
            return@post
        }
    }

    // 정상 처리
    val user = User(nextId++, request.name, request.email, request.age)
    users.add(user)
    call.respond(HttpStatusCode.Created, user)
}

예외 처리​

import io.ktor.server.plugins.statuspages.*

fun Application.module() {
    install(StatusPages) {
        exception<Throwable> { call, cause ->
            call.respond(
                HttpStatusCode.InternalServerError,
                mapOf("error" to (cause.message ?: "알 수 없는 오류"))
            )
        }

        exception<IllegalArgumentException> { call, cause ->
            call.respond(
                HttpStatusCode.BadRequest,
                mapOf("error" to cause.message)
            )
        }
    }

    routing {
        get("/error") {
            throw IllegalArgumentException("잘못된 요청입니다")
        }
    }
}

🔥 실전 패턴​

페이지네이션​

get("/products") {
    val page = call.request.queryParameters["page"]?.toIntOrNull() ?: 1
    val size = call.request.queryParameters["size"]?.toIntOrNull() ?: 10

    val start = (page - 1) * size
    val end = minOf(start + size, products.size)

    val items = if (start < products.size) {
        products.subList(start, end)
    } else {
        emptyList()
    }

    call.respond(
        mapOf(
            "page" to page,
            "size" to size,
            "total" to products.size,
            "items" to items
        )
    )
}

// 사용: GET /products?page=2&size=20

필터링과 정렬​

get("/users") {
    val nameFilter = call.request.queryParameters["name"]
    val sortBy = call.request.queryParameters["sort"]

    var result = users.toList()

    // 필터링
    if (nameFilter != null) {
        result = result.filter { it.name.contains(nameFilter, ignoreCase = true) }
    }

    // 정렬
    when (sortBy) {
        "name" -> result = result.sortedBy { it.name }
        "age" -> result = result.sortedBy { it.age }
    }

    call.respond(result)
}

// 사용: GET /users?name=김&sort=age

부분 업데이트 (PATCH)​

@Serializable
data class PatchUserRequest(
    val name: String? = null,
    val email: String? = null,
    val age: Int? = null
)

patch("/users/{id}") {
    val id = call.parameters["id"]?.toIntOrNull()
    val request = call.receive<PatchUserRequest>()

    val index = users.indexOfFirst { it.id == id }
    if (index == -1) {
        call.respond(HttpStatusCode.NotFound)
        return@patch
    }

    val user = users[index]
    val updated = user.copy(
        name = request.name ?: user.name,
        email = request.email ?: user.email,
        age = request.age ?: user.age
    )

    users[index] = updated
    call.respond(updated)
}

🎯 응답 구조화​

표준 응답 형식​

@Serializable
data class ApiResponse<T>(
    val success: Boolean,
    val data: T? = null,
    val error: String? = null
)

get("/users/{id}") {
    val id = call.parameters["id"]?.toIntOrNull()
    val user = users.find { it.id == id }

    if (user != null) {
        call.respond(
            ApiResponse(
                success = true,
                data = user
            )
        )
    } else {
        call.respond(
            HttpStatusCode.NotFound,
            ApiResponse<User>(
                success = false,
                error = "사용자를 찾을 수 없습니다"
            )
        )
    }
}

🛡️ 인증 (간단 버전)​

API Key 인증​

val validApiKeys = setOf("secret-key-1", "secret-key-2")

routing {
    route("/api") {
        // 인증 미들웨어
        intercept(ApplicationCallPipeline.Call) {
            val apiKey = call.request.headers["X-API-Key"]

            if (apiKey !in validApiKeys) {
                call.respond(
                    HttpStatusCode.Unauthorized,
                    mapOf("error" to "유효하지 않은 API Key")
                )
                finish()
            }
        }

        // 보호된 라우트
        get("/protected") {
            call.respondText("인증된 사용자만 접근 가능")
        }
    }
}

// 사용: curl -H "X-API-Key: secret-key-1" http://localhost:8080/api/protected

🤔 자주 묻는 질문​

Q1. PUT vs PATCH?​

A: PUT은 전체, PATCH는 부분 수정!

// PUT - 전체 교체
put("/users/{id}") {
    val request = call.receive<User>()
    // 모든 필드 필수
}

// PATCH - 부분 수정
patch("/users/{id}") {
    val request = call.receive<PatchUserRequest>()
    // 일부 필드만 선택적
}

Q2. 상태 코드는 언제 쓰나요?​

A: 의미에 맞게 선택!

// 200 OK - 성공
call.respond(data)

// 201 Created - 생성됨
call.respond(HttpStatusCode.Created, newItem)

// 204 No Content - 내용 없음 (삭제 시)
call.respond(HttpStatusCode.NoContent)

// 400 Bad Request - 잘못된 요청
call.respond(HttpStatusCode.BadRequest, error)

// 404 Not Found - 없음
call.respond(HttpStatusCode.NotFound)

// 500 Internal Server Error - 서버 오류
call.respond(HttpStatusCode.InternalServerError)

Q3. CORS는 어떻게 설정하나요?​

A: CORS 플러그인 사용!

install(CORS) {
    allowMethod(HttpMethod.Options)
    allowMethod(HttpMethod.Get)
    allowMethod(HttpMethod.Post)
    allowMethod(HttpMethod.Put)
    allowMethod(HttpMethod.Delete)
    allowHeader(HttpHeaders.ContentType)
    anyHost()  // 개발 환경
    // allowHost("example.com")  // 프로덕션
}

🎬 마치며​

REST API로 완전한 백엔드 구축!

핵심 정리:
✅ CRUD 완전 구현
✅ 적절한 상태 코드
✅ 요청 검증
✅ 에러 처리
✅ 페이지네이션, 필터링

다음 단계: 데이터베이스에서 데이터 영속성을 추가해보세요!