3.2 REST API 설계 원칙

REST(Representational State Transfer) API는 웹 서비스 설계의 기본으로, HTTP 요청을 통해 자원(리소스)에 접근하는 방법을 제공합니다. REST API를 설계할 때 다음과 같은 원칙을 준수해야 합니다.

1. 자원 기반의 URL 설계

REST API는 자원에 대한 접근이 가능해야 하며, 각 자원은 고유한 URI(Uniform Resource Identifier)를 가져야 합니다. 예를 들어, 사용자를 나타내는 자원의 경우 다음과 같이 설계할 수 있습니다:

• GET /users : 사용자 목록 가져오기
• GET /users/{id} : 특정 사용자 가져오기
• POST /users : 새로운 사용자 추가하기
• PUT /users/{id} : 기존 사용자 수정하기
• DELETE /users/{id} : 사용자 삭제하기

2. HTTP 메서드의 적절한 사용

HTTP 메서드는 각 기능을 명확히 하기 위해 적절하게 사용해야 합니다. 주로 사용하는 메서드는 다음과 같습니다:

• GET: 서버로부터 데이터를 조회
• POST: 서버에 새로운 데이터를 생성
• PUT: 서버의 기존 데이터를 수정
• DELETE: 서버의 데이터를 삭제

3. 상태 코드의 사용

REST API에서는 요청에 대한 결과를 상태 코드를 통해 클라이언트에게 알립니다. 예를 들어:

• 200 OK: 요청이 성공적으로 처리됨
• 201 Created: 자원이 성공적으로 생성됨
• 204 No Content: 요청이 성공했지만 반환할 데이터가 없음
• 400 Bad Request: 클라이언트 오류
• 404 Not Found: 요청한 자원을 찾을 수 없음
• 500 Internal Server Error: 서버 내부 오류가 발생함

4. 데이터 포맷

REST API에서는 주로 JSON 포맷을 사용하여 데이터를 주고받습니다. JSON은 구조가 간단하고 인기가 있어, 다양한 클라이언트에서 쉽게 사용할 수 있습니다. 예를 들어 사용자의 정보를 JSON 형식으로 표현하면 다음과 같습니다:

{
  "id": 1,
  "name": "John",
  "email": "john@example.com"
}

실습 프로젝트

이번 장에서 배운 REST API 설계 원칙을 적용하여 간단한 사용자 관리 API를 구현해보겠습니다. FastAPI를 사용하여 아래와 같이 사용할 수 있습니다:

1. FastAPI 설치: pip install fastapi uvicorn
2. 기본 사용자 API 구현:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str

users = []

@app.get("/users")
def get_users():
    return users

@app.post("/users")
def create_user(user: User):
    users.append(user)
    return user

이제 이 API를 사용하여 사용자를 추가하고 조회해보는 실습을 진행해보세요. FastAPI의 Swagger UI를 통해 API 문서를 확인할 수 있습니다. 다음 커맨드를 실행하여 서버를 시작하세요:

uvicorn main:app --reload

퀴즈

1. REST API에서 자원을 표현하기 위한 URL 설계 시 지켜야 할 원칙은 무엇인가요?
2. HTTP 상태 코드 중 404는 어떤 상황에서 사용되나요?

이번 장을 통해 REST API의 기본 원칙과 FastAPI를 활용한 간단한 사용자 관리 API를 구현하는 방법을 배웠습니다. 다음 주제는 인증 및 인가(JWT)로 넘어가겠습니다.