RESTful API 설계 (RESTful API Design)

1. 도입 (왜 배워야 하는가)

RESTful API는 현대 웹 애플리케이션에서 데이터와 서비스를 클라이언트와 서버 간에 교환하는 주요 방법입니다. 웹 서비스의 표준화된 접근 방식을 제공하여 다양한 플랫폼과 언어에서 쉽게 통신할 수 있도록 합니다.

실무에서는 RESTful API를 통해 모바일 앱, 프론트엔드 웹 애플리케이션, IoT 기기 등에서 서로 다른 시스템 간의 원활한 데이터 통신을 가능하게 합니다. 만약 RESTful API 설계를 잘못하면, 클라이언트와 서버 간의 상호작용이 원활하지 않거나, 시스템 확장이 어려워질 수 있습니다. 또한, API 문서화가 부족하면 개발자가 API를 이해하기 어렵고, 이는 프로젝트의 생산성을 떨어뜨립니다.

2. 핵심 개념 설명

REST (Representational State Transfer)

REST는 웹에서 리소스(데이터)를 정의하고 이를 HTTP 프로토콜을 통해 조작하는 아키텍처 스타일입니다. RESTful API는 특정한 규칙을 따르며, 클라이언트가 서버에 요청을 보내고 응답을 받는 방식으로 작동합니다.

리소스 (Resource)

리소스는 API에서 접근할 수 있는 데이터의 단위로, 예를 들어 사용자, 제품, 주문 등이 있습니다. 각 리소스는 고유한 URI(Uniform Resource Identifier)를 가집니다.

상태 (State)

RESTful API에서는 클라이언트가 요청할 때마다 필요한 정보(상태)를 서버에서 제공받습니다. 클라이언트는 서버에 저장된 상태를 변경할 수 있습니다.

3. 기본 코드 예제

아래는 Go 언어로 간단한 RESTful API를 구현하는 예제입니다.

package main

import (
    "encoding/json"
    "net/http"
)

type Product struct {
    ID   string  json:"id"
    Name string  json:"name"
    Price float64 json:"price"
}

var products []Product

func getProducts(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(products)
}

func main() {
    products = append(products, Product{ID: "1", Name: "Apple", Price: 0.99})
    products = append(products, Product{ID: "2", Name: "Banana", Price: 0.59})

    http.HandleFunc("/products", getProducts)
    http.ListenAndServe(":8080", nil)
}

실행 결과

• /products 엔드포인트에 GET 요청을 보내면 아래와 같은 JSON 형식으로 제품 목록이 반환됩니다.

[
    {"id":"1","name":"Apple","price":0.99},
    {"id":"2","name":"Banana","price":0.59}
]

코드 한 줄씩 동작 설명

1. package main: Go의 메인 패키지를 정의합니다.
2. import (...): 필요한 패키지를 가져옵니다.
3. type Product {...}: 제품 정보를 담기 위한 구조체를 정의합니다.
4. var products []Product: 제품 목록을 담을 슬라이스를 선언합니다.
5. func getProducts(...){...}: 제품 목록을 JSON 형식으로 반환하는 핸들러 함수를 정의합니다.
6. http.HandleFunc("/products", getProducts): /products 경로에 대한 요청을 처리할 핸들러를 등록합니다.
7. http.ListenAndServe(":8080", nil): 서버를 시작하여 8080 포트에서 요청을 대기합니다.

4. 실전 활용 예제

1. 쇼핑몰 장바구니 API

쇼핑몰에서 장바구니를 관리하는 API를 설계할 때, 사용자가 장바구니에 상품을 추가하고, 조회하고, 삭제하는 기능이 필요합니다. 이때 각각의 기능에 대해 RESTful 원칙을 적용하여 GET, POST, DELETE 메소드를 사용합니다.

2. 사용자 인증 API

사용자 로그인 및 등록을 처리하는 API를 설계할 때, POST 메소드를 사용하여 사용자 정보를 서버에 전송하고, 로그인 시에는 JWT(Json Web Token)를 사용하여 인증 정보를 반환합니다.

5. 흔한 실수와 주의사항

실수 1: 잘못된 HTTP 메소드 사용

8. 잘못된 코드:

http.HandleFunc("/products", createProduct) // POST 메소드로 제품 생성

9. 올바른 코드:

http.HandleFunc("/products", getProducts) // GET 메소드로 제품 조회

10. 설명: 각 메소드는 고유한 목적이 있으므로 이를 구분하여 사용해야 합니다.

실수 2: URI 설계 부족

11. 잘못된 코드:

/api/products/1/2  // 불필요한 정보 포함

12. 올바른 코드:

/api/products/1  // 리소스 ID만 포함

13. 설명: URI는 명확하고 간결해야 하며, 리소스를 식별하는 데 필요한 최소한의 정보만 포함해야 합니다.

6. 정리

14. RESTful API는 클라이언트와 서버 간 데이터 교환을 표준화합니다.
15. 각 리소스는 고유한 URI를 가지고, HTTP 메소드를 통해 조작됩니다.
16. API 설계 시 명확한 URI 구조와 적절한 HTTP 메소드 사용이 중요합니다.

다음에 학습하면 좋은 주제

17. GraphQL API 설계
18. API 보안 (OAuth, JWT)
19. API 문서화 도구 (Swagger, Postman)