REST API: 정의, HTTP 메서드 및 모바일 앱에서의 작동 원리

REST API란?

REST API(Representational State Transfer API)는 2000년 로이 필딩이 박사 논문에서 제안한 아키텍처 스타일입니다. 네트워크 프로토콜 설계를 위한 일련의 제약 조건과 원칙을 정의합니다. 이러한 제약 조건을 준수하는 API를 RESTful이라고 합니다. REST는 프로토콜이나 표준이 아닙니다 — 클라이언트와 서버 간 데이터 교환을 위해 기존 프로토콜(주로 HTTP)을 사용하는 아키텍처 접근 방식입니다.

REST의 핵심 아이디어는 리소스 지향 아키텍처입니다. 서버에서 메서드를 호출하는 대신(SOAP 또는 RPC에서처럼) 클라이언트는 리소스를 조작합니다: 목록을 가져오고, 새로 만들고, 업데이트하거나 삭제합니다. 각 리소스는 도메인 엔터티(사용자, 주문, 제품, 문서)입니다. 리소스에는 상태가 있으며 표준화된 형식(일반적으로 JSON)으로 클라이언트에 전송됩니다. 서버는 요청 간에 클라이언트 상태를 저장하지 않습니다 — 이것이 REST의 핵심 요구 사항인 stateless 원칙입니다.

REST API의 주요 특성:

• Stateless — 클라이언트의 각 요청에는 처리에 필요한 모든 정보가 포함됨
• Cacheable — 서버 응답은 캐시 가능 또는 불가능으로 명시적으로 표시되어야 함
• Layered system — 아키텍처에 중간 서버, 로드 밸런서, 프록시가 포함될 수 있음
• Uniform interface — HTTP 메서드, URL 및 상태 코드를 통한 통일된 상호 작용 인터페이스

REST 아키텍처의 원칙

REST는 필딩이 공식화한 6가지 아키텍처 제약 조건에 기반합니다. 이러한 제약 조건을 준수하면 확장성, 성능 및 통합 용이성이 보장됩니다. 각 원칙은 캐싱 필요성부터 보안 요구 사항에 이르기까지 분산 시스템의 특정 문제를 해결합니다. 각 원칙을 자세히 살펴보겠습니다.

Uniform Interface 원칙에는 추가로 네 가지 하위 제약 조건이 포함됩니다: URI를 통한 리소스 식별, 표현을 통한 리소스 조작, 자기 서술적 메시지 및 HATEOAS(애플리케이션 상태 엔진으로서의 하이퍼미디어). 마지막 하위 제약 조건은 실제로 종종 무시됩니다 — 대부분의 최신 REST API는 HATEOAS를 완전히 구현하지 않으며, 이러한 API가 “진정으로” RESTful인지에 대한 논의로 이어집니다.

Stateless 원칙은 확장에 가장 중요한 원칙 중 하나입니다. 서버에 세션이 없으면 모든 서버 인스턴스가 모든 요청을 처리할 수 있습니다. 이는 수평 확장을 단순화합니다: 로드 밸런서 뒤에 새 서버를 추가하기만 하면 됩니다. 모바일 애플리케이션의 경우 stateless는 요청을 모든 CDN 서버로 보낼 수 있음을 의미하며, 이는 글로벌 가용성에 중요합니다.

REST의 HTTP 메서드

REST API의 각 HTTP 메서드는 리소스에 대한 특정 작업에 해당합니다: GET은 읽기, POST는 생성, PUT은 전체 업데이트, PATCH는 부분 업데이트, DELETE는 삭제입니다. 메서드의 멱등성은 핵심 특성입니다: GET, PUT, DELETE는 멱등적(반복 실행이 동일한 결과 제공)이고 POST와 PATCH는 그렇지 않습니다. 이는 요청이 서버에 도달했는지 클라이언트가 알 수 없는 네트워크 오류를 처리하는 데 중요합니다.

• GET — 리소스 또는 리소스 목록 검색. 멱등적, 서버 상태 변경하지 않음
• POST — 새 리소스 생성. 비멱등적, 각 호출이 새 리소스 생성
• PUT — 리소스 전체 교체. 멱등적, 첫 번째 이후 반복 호출이 상태 변경하지 않음
• PATCH — 리소스 부분 업데이트. 부분적으로 멱등적(구현에 따라 다름)
• DELETE — 리소스 삭제. 멱등적, 반복 삭제 시 오류 대신 404 반환

HTTP 상태 코드는 REST API의 필수적인 부분입니다. 각 코드는 특정 의미를 갖습니다: 성공적인 GET의 경우 200 OK, POST의 경우 201 Created, 응답 본문 없는 DELETE의 경우 204 No Content, 잘못된 데이터의 경우 400 Bad Request, 인증 부족 시 401 Unauthorized, 리소스 없음 시 404 Not Found. 상태 코드를 올바르게 사용하면 API가 자체 문서화되고 디버깅이 간소화됩니다.

데이터 형식: JSON 및 기타

JSON(JavaScript Object Notation)은 REST API에서 데이터 전송의 주요 형식입니다. 그 인기는 단순성, 사람이 읽기 쉬움 및 JavaScript의 기본 지원 때문입니다. JSON은 Content-Type: application/json 헤더와 함께 전송됩니다. 대안으로는 XML(장황함, 노후화), YAML(구성에 편리, API에는 덜 일반적), Protocol Buffers(바이너리, 고부하 시스템에 효율적)가 있습니다.

REST API의 JSON 객체 구조에는 일반적으로 id, type 필드 및 리소스 속성이 포함됩니다. 컬렉션의 경우 페이지네이션 메타데이터가 포함된 JSON 배열이 사용됩니다. 최신 REST API는 응답 검증을 위해 JSON:API 사양(jsonapi.org) 또는 JSON Schema를 따릅니다. 통일된 데이터 형식을 사용하면 클라이언트 라이브러리 개발 및 문서 생성이 간소화됩니다.

사용자 목록에 대한 JSON 응답 예제:

{
    "data": [
        {
            "id": 1,
            "name": "안나 페트로바",
            "email": "anna@example.com"
        }
    ],
    "meta": {
        "total": 42,
        "page": 1,
        "per_page": 10
    }
}

데이터 전송 형식의 선택은 모바일 애플리케이션 성능에 영향을 미칩니다. JSON은 GZIP을 통해 70-80% 압축되어 대부분의 시나리오에서 허용 가능합니다. 대량의 데이터(스트리밍, 게임)가 있는 실시간 애플리케이션의 경우 바이너리 프로토콜로 전환하거나 Protocol Buffers와 함께 WebSocket을 사용하는 것이 좋습니다.

REST API 요청 예제

모바일 애플리케이션 측에서 REST API 작업의 실제 예제를 살펴보겠습니다. 예시로 온라인 스토어에서 주문을 처리하는 API를 가져옵니다. 각 HTTP 메서드에 대해 요청과 예상 서버 응답이 표시됩니다. 예제는 모바일 개발에서 사용되는 일반적인 RESTful API 구조를 보여줍니다.

GET — 주문 목록 검색

페이지네이션이 적용된 모든 사용자 주문을 검색하는 요청입니다. 응답에는 주문 객체 배열과 페이지 탐색을 위한 메타 정보가 포함됩니다. page 및 per_page 매개변수는 쿼리 문자열을 통해 전달됩니다.

// REST API용 Retrofit 인터페이스
interface OrderApi {
    @GET("api/v1/orders")
    suspend fun getOrders(
        @Query("page") page: Int = 1,
        @Query("per_page") perPage: Int = 20
    ): Response<OrderListResponse>
}

POST — 새 주문 생성

POST 요청을 통한 새 주문 생성. 서버는 201 Created 상태와 응답 본문에 생성된 객체를 반환합니다. 중요: 생성은 특정 리소스가 아닌 컬렉션 /api/v1/orders에서 이루어집니다 — 이는 표준 RESTful 패턴입니다.

@POST("api/v1/orders")
suspend fun createOrder(
    @Body order: CreateOrderRequest
): Response<OrderResponse>

// 요청 본문 예제
data class CreateOrderRequest(
    val productId: String,
    val quantity: Int,
    val addressId: String
)

DELETE — 주문 삭제

리소스 삭제는 특정 주문 URL에 DELETE 메서드로 수행됩니다. 성공적인 삭제는 204 No Content를 반환합니다. DELETE의 멱등성은 동일한 URL에 대한 반복 요청이 404 Not Found를 반환하며 클라이언트에서 올바르게 처리됨을 의미합니다.

@DELETE("api/v1/orders/{id}")
suspend fun deleteOrder(
    @Path("id") orderId: String
): Response<Unit>

// ViewModel에서 사용
fun removeOrder(orderId: String) {
    viewModelScope.launch {
        val response = api.deleteOrder(orderId)
        if (response.isSuccessful) {
            showSuccess()
        }
    }
}

이 예제는 Retrofit 및 Kotlin Coroutines를 사용한 Android 측의 일반적인 REST API 구현을 보여줍니다. iOS 애플리케이션의 경우 URLSession 또는 Alamofire 라이브러리가 Codable 프로토콜과 함께 유사한 역할을 수행합니다. REST API 구조는 플랫폼에 관계없이 동일하게 유지됩니다 — 요청을 수행하는 방식만 변경됩니다.

RESTful API 디자인: 실용적인 권장 사항

고품질 RESTful API를 설계하려면 개발자에게 직관적인 API를 만드는 규칙을 따라야 합니다. 리소스는 복수 명사(/users, /orders, /products)로 명명하고, HTTP 메서드는 작업을 반영하며, URL은 중첩 계층 구조를 나타내야 합니다. 오류는 HTTP 상태뿐만 아니라 코드와 메시지가 포함된 표준화된 JSON을 반환해야 합니다. 이러한 규칙을 따르면 새로운 개발자의 진입 장벽이 낮아지고 통합이 간소화됩니다.

• 리소스 명명 — 복수형, kebab-case: /api/v1/user-orders (/api/v1/getUserOrders 아님)
• 필터링 및 정렬 — 쿼리 매개변수 사용: ?status=active&sort=created_at:desc
• 페이지네이션 — 대규모 데이터셋은 커서 기반, 소규모는 페이지 기반
• 버전 관리 — URL(/api/v2/) 또는 Accept-Version 헤더 사용
• 오류 — 통일된 형식: { "error": { "code": "VALIDATION_ERROR", "message": "..." } }
• 속도 제한 — X-RateLimit-Remaining 및 Retry-After 헤더

REST API 설계 시 일반적인 실수는 과도한 리소스 중첩입니다. /users/1/orders/5/items/3 대신 쿼리 매개변수가 있는 평면 구조 /items?order_id=5&user_id=1을 사용하는 것이 좋습니다. 이는 캐싱을 단순화하고 서버에서 긴 경로를 유지할 필요가 없으며 문서화가 더 쉽습니다. 평면 아키텍처는 향후 GraphQL로 마이그레이션할 때 그래프 기반 쿼리와의 호환성도 더 좋습니다.

REST API 보안은 인증(JWT, OAuth 2.0) 및 리소스 수준의 권한 부여를 통해 구현됩니다. 각 요청은 사용자가 요청한 리소스에 대한 액세스 권한이 있는지 확인해야 합니다. HTTPS는 필수입니다 — 암호화 없이 토큰과 데이터가 일반 텍스트로 전송됩니다. 모바일 애플리케이션의 경우 안전한 토큰 획득을 위해 PKCE(Proof Key for Code Exchange)와 함께 OAuth 2.0을 사용하는 것이 좋습니다.

버전 관리 및 캐싱

REST API의 버전 관리는 변경 시 하위 호환성을 위해 필요합니다. 가장 일반적인 접근 방식은: URL에 버전 포함(/api/v1/orders), 헤더에 버전 포함(Accept: application/vnd.myapi.v1+json), 쿼리 매개변수에 버전 포함(?api_version=1)입니다. URL 버전 관리는 로그와 문서에서 명시적으로 확인할 수 있어 가장 인기 있는 방법입니다. 그러나 리소스당 단일 URL이라는 REST 원칙을 위반합니다.

REST API의 캐싱은 HTTP 헤더 Cache-Control, ETag 및 Last-Modified를 통해 구현됩니다. 캐시 가능으로 표시된 GET 요청은 서버에 연결하지 않고 브라우저 또는 프록시 캐시에서 제공될 수 있습니다. 모바일 애플리케이션의 경우 캐싱이 특히 중요합니다 — 데이터 사용량을 줄이고 연결 상태가 좋지 않을 때 이전에 로드된 데이터 표시를 가속화합니다. ETag는 응답 콘텐츠의 해시입니다: 클라이언트가 If-None-Match로 보내고 데이터가 변경되지 않은 경우 서버가 304 Not Modified를 반환합니다.

REST API의 현대적 대안으로는 GraphQL(유연한 클라이언트 측 데이터 가져오기)과 gRPC(마이크로서비스를 위한 HTTP/2 기반 바이너리 프로토콜)가 있습니다. 그러나 REST는 단순성, 보편성 및 광범위한 도구 지원으로 인해 공개 API의 주요 표준으로 남아 있습니다. REST와 대안 간의 선택은 프로젝트의 특정 요구 사항(쿼리 복잡성, 데이터 볼륨, 실시간 업데이트 필요성)에 따라 달라집니다.