FastAPI는 Python으로 RESTful API를 설계하기 위한 강력한 도구를 제공합니다.
FastAPI로 개발할 때도 RESTful 설계 원칙을 준수하는 것이 중요하며, 이를 통해 API의 가독성과 유지보수성을 향상시킬 수 있습니다.
아래는 FastAPI에서 RESTful API 설계 시 따라야 할 규칙과 작성 예제
1. RESTful 원칙 준수
FastAPI에서도 일반적인 RESTful API 설계 원칙을 따르는 것이 중요하기 때문에 명사 기반의 URI, 적절한 HTTP 메서드, 상태 코드 반환 등을 준수해야 합니다.
from fastapi import FastAPI
app = FastAPI()
# 기본적인 CRUD 예제
@app.get("/users")
def get_users():
return [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
@app.get("/users/{user_id}")
def get_user(user_id: int):
return {"id": user_id, "name": "Alice"}
@app.post("/users")
def create_user(user: dict):
return {"id": 3, "name": user["name"]}
@app.put("/users/{user_id}")
def update_user(user_id: int, user: dict):
return {"id": user_id, "name": user["name"]}
@app.delete("/users/{user_id}")
def delete_user(user_id: int):
return {"message": f"User {user_id} deleted"}
2. Path와 Query Parameter
Path와 Query Parameter를 구분
Path Parameter는 특정 리소스를 식별할 때 사용
Query Parameter는 필터링, 정렬, 페이징에 사용
@app.get("/products")
def get_products(category: str = None, page: int = 1, limit: int = 10):
return {"category": category, "page": page, "limit": limit}
3. Pydantic 모델 활용
FastAPI는 데이터 유효성 검증을 위해 Pydantic 모델을 지원합니다.
이를 사용하여 입력 데이터의 구조를 정의하고 검증하는 것이 좋습니다.
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
email: str
@app.post("/users")
def create_user(user: User):
return {"message": f"User {user.name} created!"}
4. HTTP 상태 코드 활용
FastAPI는 status 모듈을 통해 HTTP 상태 코드를 쉽게 정의할 수 있습니다. 응답에서 적절한 상태 코드를 반환
from fastapi import HTTPException, status
@app.get("/users/{user_id}")
def get_user(user_id: int):
if user_id != 1:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found"
)
return {"id": user_id, "name": "Alice"}
5. API 버전 관리
버전을 명시적으로 관리하여 변경에 유연하게 대처
from fastapi import APIRouter
api_v1 = APIRouter()
@api_v1.get("/users")
def get_users():
return [{"id": 1, "name": "Alice"}]
app.include_router(api_v1, prefix="/v1")
6. Swagger와 Redoc 문서화 활용
FastAPI는 자동으로 Swagger와 Redoc 문서를 생성해줍니다.
이를 통해 API의 가독성과 사용성을 높일 수 있습니다.
FastAPI를 실행하면 /docs (Swagger)와 /redoc (Redoc)에서 문서를 확인할 수 있습니다.
엔드포인트에 명확한 설명을 추가하면 문서화가 더 풍부해집니다.
@app.get("/users", summary="Get Users", description="Retrieve a list of users.")
def get_users():
return [{"id": 1, "name": "Alice"}]
7. 보안 고려
FastAPI는 OAuth2 및 JWT 토큰 인증을 기본적으로 지원합니다.
인증 및 권한 관리를 통해 보안을 강화하세요.
from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
@app.get("/secure-data")
def secure_data(token: str = Depends(oauth2_scheme)):
return {"message": "This is secure data"}
8. 필터링, 정렬, 페이징 지원
RESTful API의 필수 기능인 필터링, 정렬, 페이징을 쿼리 파라미터로 구현
@app.get("/items")
def get_items(sort: str = "asc", limit: int = 10):
# 예제: 정렬과 제한 구현
items = [{"id": i, "name": f"Item {i}"} for i in range(1, 21)]
sorted_items = sorted(items, key=lambda x: x["id"], reverse=(sort == "desc"))
return sorted_items[:limit]
9. 유닛 테스트 및 로깅
FastAPI는 TestClient를 통해 간단한 유닛 테스트를 지원합니다.
또한, 로깅을 사용하여 API의 동작을 추적합니다.
from fastapi.testclient import TestClient
client = TestClient(app)
def test_get_users():
response = client.get("/users")
assert response.status_code == 200
assert isinstance(response.json(), list)
10. 최적화와 확장성
중복 코드를 줄이고, Dependency Injection을 사용하여 재사용성을 높여주기.
비동기 처리를 통해 성능을 최적화
from fastapi import Depends
def get_db():
# 예: 데이터베이스 연결
return "db_connection"
@app.get("/data")
def get_data(db: str = Depends(get_db)):
return {"db": db}
