REST API 이해하기 (iOS URLSession 사용 예시 포함)

 

지난 게시글에서는 HTTP에 대해서 공부했습니다.

이번에는 REST API라는 용어에 대해 공부해보려고 합니다.

 

1. REST의 기본 원칙

REST는 특정 프로토콜(예: HTTP)을 따르며, 아래와 같은 규칙들이 있습니다.

 

1) 자원(Resource) 기반

• REST API의 기본 단위는 '자원'
• 자원은 URL(Uniform Resource Locator)로 식별
  • 예: https://api.example.com/users/123
    • users: 자원의 유형
    • 123: 특정 자원의 ID
• 자원은 보통 '명사' 형태로 표현

 

2) HTTP 메서드 사용

REST는 HTTP 메서드를 통해 자원에 어떤 동작을 할지 정의합니다.

• GET: 데이터 조회
• POST: 생성
• PUT: 수정
• PATCH: 부분 수정
• DELETE: 삭제

 

3) 상태 비저장성 (Stateless)

• REST API는 클라이언트와 서버 간의 요청이 독립적이어야 합니다.
• 서버는 요청 간 상태를 유지하지 않습니다. 즉, 각 요청은 필요한 모든 정보를 포함
  • 예: 인증 정보(JWT 토큰 등)는 매 요청에 포함되어야 합니다.

 

4) 표현 (Representation)

• 자원의 데이터는 여러 포맷으로 표현 가능
  • JSON, XML, HTML 등
• JSON이 가장 널리 사용됨

{
  "id": 123,
  "name": "CrazyDeer Kim",
  "email": "kim@example.com"
}

 

 

5) HTTP 상태 코드 사용

REST API는 작업 결과를 HTTP 상태 코드로 응답

• 200
• 201
• 400
• 401
• 404
• 500

상태 코드에 관해서는 다음 게시글에 더욱 자세히 설명되어 있습니다.

HTTP의 정의, 기본 작동 원리, 요청/응답 구조, HTTP/HTTPS

 

2. REST API 설계의 좋은 예

명확하고 예측이 가능해야 합니다.

사용자(User) 관리 API

• 전체 사용자 조회
  • Endpoint: GET /users
  • 의미: 모든 사용자 정보를 가져옴
• 특정 사용자 조회
  • EndPoint: GET /users/{id}
  • 의미: 특정 ID를 가진 사용자 정보 조회
• 새로운 사용자 생성
  • Endpoint: POST /users
  • 의미: 새로운 사용자 추가
  • 요청 본문

{
  "name": "CrazyDeer Kim",
  "email": "kim@example.com"
}

• 사용자 정보 수정
  • Endpoint: PUT /users/{id}
  • 의미: 사용자 정보 전체 업데이트
  • 요청 본문

{
  "name": "MadDeer Kim",
  "email": "mad@example.com"
}

• 사용자 삭제
  • Endpoint: DELETE /users/{id}
  • 의미: 특정 사용자 삭제

 

3. REST API를 iOS에서 사용

URLSession을 사용해보겠습니다.

 

• GET

let url = URL(string: "https://api.example.com/users")!
var request = URLRequest(url: url)
request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let error = error {
        print("Error: \(error)")
        return
    }
    
    if let data = data {
        do {
            let users = try JSONSerialization.jsonObject(with: data, options: [])
            print(users)
        } catch {
            print("JSON Parsing Error: \(error)")
        }
    }
}

task.resume()

 

• POST

let url = URL(string: "https://api.example.com/users")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")

let body: [String: Any] = ["name": "John Doe", "email": "john@example.com"]
request.httpBody = try? JSONSerialization.data(withJSONObject: body)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let error = error {
        print("Error: \(error)")
        return
    }
    
    if let data = data {
        do {
            let createdUser = try JSONSerialization.jsonObject(with: data, options: [])
            print(createdUser)
        } catch {
            print("JSON Parsing Error: \(error)")
        }
    }
}

task.resume()

 

iOS 개발을 하면서 무심코 지나갔던 부분이 있는데 바로 이것입니다.

request.setValue("application/json", forHTTPHeaderField: "Content-Type")

 

이는 HTTP 요청의 헤더(Header)에서 Content-Type 필드의 값을 application/json으로 설정하는 코드입니다.

이 설정은 서버와의 통신에서 매우 중요한 역할을 합니다.

 

Content-Type 헤더란?

HTTP 요청의 Content-Type 헤더는 요청 본문(Request Body)의 데이터 형식을 서버에 알리는 역할을 합니다.

• 서버는 이 헤더를 보고 클라이언트가 보내는 데이터가 어떤 형식인지 판단합니다.
• 클라이언트가 데이터를 보낼 때 올바른 데이터 형식을 명시하지 않으면, 서버가 요청을 이해하지 못할 가능성이 큽니다.

 

application/json의 의미

요청 본문이 JSON 포맷이라는 것을 나타냅니다.

JSON 데이터를 서버에 보내려면, 서버가 JSON 형식임을 알아야 하므로 Content-Type: application/json 헤더를 설정해야 하는 것입니다.

 

서버는 위 정보들로 클라이언트로부터 어떤 형식으로 데이터가 오겠다 라는 것을 예상하고 요청 본문을 JSON 파싱 처리합니다.

JSON이 아닌 데이터가 오면, 400 Bad Request와 같은 에러를 반환할 수도 있습니다.

 

이외에 다른 Content-Type 값들

• application/x-www-form-urlencoded
  • 폼 데이터를 URL 인코딩 방식으로 전송할 때 사용
  • 예: key1=value1&key2=value2
• multipart/form-data
  • 파일 업로드나 복잡한 폼 데이터를 전송할 때 사용
• text/plain
  • 순수 텍스트 데이터를 전송할 때 사용

 

4. REST API 사용 시 유의 사항

1. 일관성 유지: 엔드포인트와 HTTP 메서드를 일관되게 설계합니다.
2. 명사형 엔드포인트: 자원의 이름은 명사로 표현
   
   1. /create-user ❌
   2. /users와 POST 메서드 활용 ✅
3. 버전 관리: API의 변경을 관리하기 위해 버전 사용
   1. 예: api.example.com/v1/users
4. 필요한 데이터만 반환: 클라이언트가 필요로 하는 데이터를 과도하게 포함하지 않아야 합니다.
   1. 필요 시 쿼리 파라미터를 사용합니다.
5. HTTP 상태 코드 적절히 사용: 클라이언트가 요청 결과를 명확히 이해할 수 있도록 상태 코드 반환

 

여기까지 REST API에 대해 자세히 알아보았습니다.

다음 게시글에서는 지금 업무 중에 사용하고 있는 RxSwift와 Moya 라이브러리와 접목시켜

REST API를 실무와 관련지어 공부해보겠습니다.