Python & FastAPI 로 백엔드 시작하기 (2) _ API 연습 및 단축 스크립트 만들기

02. API 연습 및 단축 스크립트 만들기

 

개요

- `main.py` 를 `app/views` 경로로 이동합니다.  
- `main.py` 에 연습용 API를 구현합니다.  
- `run-server.sh` 스크립트를 생성합니다.  
- `tree` 를 이용해 디렉터리 구조를 확인합니다.

 

 

 

---

 

 

main.py 를 app/views 경로로 이동하기

 

app 디렉터리와 그 하위에 views 디렉터리를 생성합니다.

 

각 디렉터리에는 __init__.py 파일을 생성합니다.
*__init__.py 파일이 없는 경우, 해당 디렉터리는 단순한 디렉터리로 간주됩니다. 반면 __init__.py 파일이 존재하는 디렉터리는 파이썬 패키지로 간주되며, 패키지 내부에 있는 모듈들을 다른 모듈에서 import할 수 있습니다.

 

기존 main.py 을 views 디렉터리로 이동시킵니다.

 

아래와 같은 형태의 디렉터리 구조가 될 것입니다.

.
├── .gitignore
├── .pre-commit-config.yaml
├── .python-version
├── README.md
├── app
├── ├── __init__.py
│   └── views
│       ├── __init__.py
│       └── main.py
├── poetry.lock
└── pyproject.toml

 

 

 

---

 

 

main.py 안에 연습용 API 구현하기

 

아래 코드를 main.py에 입력해주세요.

# main.py


from typing import Any
from fastapi import Body, FastAPI


from pydantic import BaseModel

app = FastAPI()


@app.get("/")
async def root() -> dict[str, Any]:
    return {"message": "Hello World"}


# path parameter 를 사용한 GET API.
@app.get("/path-items/{item_id}")
async def read_item_by_path(item_id: int) -> dict[str, Any]:
    return {"item_id": item_id}


# query parameter 를 사용한 GET API.
@app.get("/query-items")
async def read_item_by_query(item_id: int) -> dict[str, Any]:
    return {"item_id": item_id}


class Item(BaseModel):
    id: int
    name: str


# BaseModel 을 사용한 POST API.
@app.post("/model-items")
async def create_item_by_model(item: Item) -> Item:
    return item


# body 를 사용한 POST API.
@app.post("/body-items")
async def create_item_by_body(
    id: int = Body(embed=True), name: str = Body(embed=True)
) -> dict[str, Any]:
    item = {"id": id, "name": name}
    return item

 

위 코드는 다양한 방식으로 데이터를 전달받는 연습용 API입니다.

 

연습용 API에서 사용한 '패스 파라미터', '쿼리 파라미터', '바디'는 HTTP 의 기본적인 데이터 전달 방식으로 각각은 다음과 같은 특징을 가집니다.

 

패스 파라미터(Path Parameter) - URL의 일부분으로 전달되는 데이터입니다. 자원을 식별하는 데 사용되며, RESTful API에서 자주 사용됩니다.

GET http://example.com/articles/123  # '/'로 구분하여 입력

 

쿼리 파라미터(Query Parameter) - URL의 끝에 '?' 다음에 키-값 쌍으로 전달되는 데이터입니다. 주로 필터링, 정렬 등의 조건을 전달할 때 사용됩니다.

GET http://example.com/search?q=python  # 'q'는 key, 'python'은 value에 해당

 

바디(Body) - POST, PUT, PATCH와 같은 HTTP 메서드에서 사용되는 데이터 전달 방식입니다. JSON, XML, Form Data 등 다양한 형식으로 전달될 수 있으며, 주로 클라이언트에서 서버로 큰 데이터를 전송할 때 사용됩니다.

POST http://example.com/api/users  # { "name": "Daco", "age": 25 } url에 포함하지 않음

아래 명령어를 통해 서버를 실행시키고 OpenAPI 문서를 통해 직접 확인해 봅시다.

uvicorn app.views.main:app --reload

 

 

 

패스 파라미터(Path Parameter)

 

 

 

쿼리 파라미터(Query Parameter)

 

 

 

 

바디(Body)

 

OpenAPI 문서를 이용해 직접 데이터를 보내보고 차이점을 파악해보세요.

더 자세한 데이터 수신 방법과 API 구현을 알고 싶다면 공식문서를 참고해주세요.

 

 

 

 

---

 

 

 

dev 폴더와 run-server.sh 스크립트 생성하기

 

main.py 의 경로가 변경됨에 따라 서버를 실행하는 명령어도 길어졌습니다. 이처럼 길어진 명령어는 외우기 어려우므로 쉽게 실행할 수 있는 명령어 스크립트를 생성하겠습니다.

 

먼저 루트 디렉터리에서 dev 폴더를 생성합니다. dev 폴더 안에 run-server.sh 스크립트 파일을 생성합니다.

스크립트 파일에는 아래처럼 서버를 실행시키는 명령어를 입력합니다.

#!/bin/bash

uvicorn app.views.main:app --reload

#!/bin/bash 를 상단에 기재하는 이유는 스크립트를 실행할 때 Bash 셸을 사용하도록 보장하기 위해서입니다. Bash는 다양한 기능과 사용성을 제공하며, 스크립트에서 변수, 제어 구조, 함수 등을 사용할 수 있습니다.

 

스크립트를 실행하기 전에 다음 명령어로 실행 권한을 부여합니다.

chmod +x dev/*

 

아래 명령어로 서버가 실행되는지 확인합니다.

dev/run-server.sh

---

 

 

tree 를 이용해 디렉터리 구조 파악하기 (선택)

 

tree는 파일 시스템의 디렉터리 구조를 보여주는 명령어입니다. 특정 디렉토리의 하위 디렉토리와 파일을 트리 구조로 보여주어 사용자가 쉽게 디렉토리 구조를 파악할 수 있도록 도와줍니다.

 

만약 tree 가 설치되어 있지 않다면 brew 명령어를 통해 설치합니다.

brew install tree

 

설치가 되었다면 tree 명령어로 디렉터리 구조를 볼 수 있습니다.

tree

 

이제 프로젝트를 진행하면서 변경되는 디렉터리 구조를 확인할 수 있습니다.

 

 

추가로 show-tree.sh 라는 스크립트를 만들고 명령어 옵션을 추가하여 불필요한 파일은 tree에서 제외시켜보겠습니다.

#!/bin/bash

tree -a -I '.git' -I '.mypy_cache' -I '.ruff_cache' -I '.pytest_cache' -I '.venv' -I __pycache__ -I __init__.py

 

 

명령어를 실행해봅시다.

dev/show-tree.sh

 

 

현재 lovelingo의 디렉터리 구조입니다.

.
├── .gitignore
├── .pre-commit-config.yaml
├── .python-version
├── README.md
├── app
│   └── views
│       └── main.py
├── dev
│   ├── run-server.sh
│   └── show-tree.sh
├── poetry.lock
└── pyproject.toml

 

---

 

 

마치며

이 글에서는 FastAPI를 사용하여 패스 파라미터, 쿼리 파라미터, 바디 데이터 수신 방법에 대해 알아보았습니다. 이제 이러한 기본 개념을 바탕으로 다양한 API를 구현하고 효과적으로 클라이언트와 데이터를 주고받을 수 있습니다.

 

또한 스크립트로 명령어를 실행하는 방법을 알아보았습니다. 스크립트를 활용하면 서버 실행 뿐만 아니라, 테스트, 정적 분석과 같은 다양한 실행 명령을 스크립트로 만들어 둘 수 있습니다. 이제는 명령어를 외우지 않아도 쉽고 빠르게 원하는 동작을 수행할 수 있습니다.

 

다음 글에서는 서비스 요구사항을 확인하고 테스트 환경을 구축하여 본격적인 API 개발을 시작해보겠습니다.