[FastAPI] Tutorial(1)

※ FastAPI Tutorial을 공부하며 이해한대로 작성한 내용으로, 실제 내용과 다르거나 틀린 부분이 있을 수 있습니다. 댓글로 알려주시면 즉시 반영하겠습니다. 감사합니다.

※ 중간에 이해하지 못해 영어로 옮겨둔 부분이 있습니다. 추후 수정하겠습니다.

https://fastapi.tiangolo.com/ko/tutorial/

자습서 - 사용자 안내서 - 도입부 - FastAPI

---

1. 첫걸음

1. FastAPI import

from fastapi import FastAPI

2. 인스턴스 생성

app = FastAPI()

3. 경로 동작 생성

@app.get('/')

• 경로: URL의 마지막 부분 ⇒ https://example.com/item/test 의 경로 = /item/test
• 동작: HTTP의 Method 중 하나
  • POST / GET / PUT / DELETE
    • 데이터 생성 / 데이터 읽기 / 데이터 업데이트 / 데이터 삭제
  • OPTIONS / HEAD / PATCH / TRACE

4. 경로 동작 함수 정의

async def root(): 
    return {"message": "Hello World"}

• URL / 에 대한 요청을 받을 때마다 호출되도록 작성됨.
• 파이썬 함수와 동일, list, dict, str, int 등을 반환할 수 있다.

---

2. 경로 매개변수

• 매개변수 / 변수를 경로에 선언 가능
  • 이렇게 하고 http://127.0.0.1:8000/items/darling 와 같이 items 뒤에 아무 내용을 써넣으면
  • {"item_id":"darling"}와 같이 변수로 전달된다.
• 타입이 있는 매개변수

@app.get('/items/{item_id}') 
async def read_item(item_id: int): 
	return {"item_id": item_id}

• 매개변수 타입을 지정할 수 있다. 이렇게 되면 int 형이 아닌 다른 자료형들을 넣을 경우 에러 발생.

{
	"detail":[
    	{
            "loc":["path","item_id"],
            "msg":"value is not a valid integer",
            "type":"type_error.integer"
        }
    ]
 } 
 INFO: 127.0.0.1:63901 - "GET /items/darling HTTP/1.1" 422 Unprocessable Entity

고정 경로를 가진 데이터에 대한 선언 순서

• python은 script 기반 → 위에서부터 정의하기 때문에 고정 경로를 가변 경로보다 먼저 선언해줘야한다.

from fastapi import FastAPI 

app = FastAPI() 

@app.get("/users/me") 
async def read_user_me(): 
	return {"user_id": "the current user"} 
    
@app.get("/users/{user_id}") 
async def read_user(user_id: str): 
	return {"user_id": user_id}

• ⇒ /users/me 로 접속하면 {"user_id":"the current user"} 가 정상적으로 출력되고, /user/others 로 접속하면 {"user_id":"others"} 로 유저 아이디를 출력한다.

@app.get("/users/{user_id}") 
async def read_user(user_id: str): 
	return {"user_id": user_id} @app.get("/users/me") 

@app.get("/users/me")
async def read_user_me(): 
	return {"user_id": "the current user"}

• ⇒ /user/me 로 접속했을 때 위 함수가 먼저 정의되어서 아래 함수의 me가 {user_id} 아래로 들어가게 되어 {"user_id":"me"} 라는 결과가 도출된다.

사전 정의 경로

• 경로 매개변수처럼 전부 오픈되어있는 것이 아니라 케이스 몇 개 중에 선택할 수 있도록 하기 위한 것. Enum 상속 클래스를 활용해서 사전에 클래스로 정의할 수 있다.

from enum import Enum

from fastapi import FastAPI


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

• 결과

# https://127.0.0.1:8000/models/alexnet
{"model_name":"alexnet","message":"Deep Learning FTW!"}

# https://127.0.0.1:8000/models/lenet
{"model_name":"lenet","message":"LeCNN all the images"}

경로 포함하는 경로 매개변수

⇒ /files/{file_path} 의 경로 동작에서 필요로 하는 file path가 /root/dnai/myfile.xtx 처럼 경로 자체인 경우 url이 /files/root/dnai/myfile.txt 가 된다 → Open API에서 지원하지 않음

그러나 FastAPI에서는 가능~

/files/{file_path:path}

• 매개변수 이름 = file_path, :path 는 매개변수가 경로와 일치해야함을 명시

@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

http://127.0.0.1:8000/files/C:/Users/dk866/Desktop/bearing_test/README.md
{"file_path":"C:/Users/dk866/Desktop/bearing_test/README.md"}

---

3. 쿼리 매개변수

경로 매개변수가 아닌 함수 자체의 매개변수 = 쿼리 매개변수

from fastapi import FastAPI

app = FastAPI()

item_db = [{'itemname' : "va"}, {'itemname' : "mr"}, {'itemname' : "lk"}, {'itemname' : "ie"}, {'itemname' : "sy"}]

@app.get('/')
async def root():
    return 'Hello World'

@app.get('/items/')
async def read_item(skip: int = 0, limit: int = 10):   # skip, limit가 쿼리 매개변수
    return item_db[skip:skip + limit]

• url 안에서 ? 를 기준으로 쿼리 매개변수 영역으로 들어가고, & 로 매개변수를 구분함
  • ex) http://127.0.0.1:3000/items/?skip=0&limit=3
  • 기본값에 대한 설정은 일반 파이썬 함수와 동일
• 선택적 매개변수
  • 기본값을 None으로 설정한 경우 → 필요한 경우 쓰고 아니면 안 쓰는 것. if문으로 있는 경우와 아닌 경우를 처리해주면 됨.

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str, q: Union[str, None] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

• Bool 형에 대한 범용성
  • True = 1 = true = on = yes = 대문자

필수 쿼리 매개변수

경로 함수 안에서 자료형 선언 + 기본값 None으로 설정해주면 필수 쿼리 매개변수

@app.get('/items/')
async def read_item(skip: int, limit: int = 10):
    return item_db[skip: skip + limit]

• http://127.0.0.1:3000/items/ ⇒ value_error.missing
• http://127.0.0.1:3000/items/?skip=3 ⇒ [{"itemname":"ie"},{"itemname":"sy"}]

@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str, needy: str, skip: int = 0, limit: Union[int, None] = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item

이 경우에는 needy는 필수, skip은 기본값이 0인 integer, limit는 선택적 쿼리 매개변수가 된다.

---

4. Request Body

Request Body : 클라이언트 → API로 데이터를 보내는 것

Response body : API → 클라이언트로 데이터를 보내는 것

• API에서는 늘 Response body를 보내야하지만 클라이언트 쪽에서는 그럴 필요 없다.
  • 클라이언트에서 보내주는 데이터를 ‘이렇게 해주세요’ 하고 규격을 주는 의미? 쉽게 클래스에서 데이터를 불러와서 갖다쓸 수 있다.

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Union

class Item(BaseModel):
    name: str
    description: Union[str, None] = None # optional 
    price: float
    tax: Union[float, None] = None # optional

app = FastAPI()

@app.post('/items/')
async def create_item(item: Item):
    return item

→ docs에서 실험

# request body
{
  "name": "puppet",
  "description": "pebric doll",
  "price": 22480,
  "tax": 1237
}

# response body
{
  "name": "puppet",
  "description": "pebric doll",
  "price": 22480,
  "tax": 1237
}
# curl
curl -X 'POST' \
  'http://127.0.0.1:2000/items/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "puppet",
  "description": "pebric doll",
  "price": 22480,
  "tax": 1237
}'

• 업데이트

@app.post('/items/')
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

# request
{
  "name": "o",
  "description": "s",
  "price": 80,
  "tax": 1
}

# response
{
  "name": "o",
  "description": "s",
  "price": 80,
  "tax": 1,
  "price_with_tax": 81
}

• request body + 경로 매개변수

@app.put("items/{item_id}")
async def create_item(item_id: int, item: Item):
	return {"item_id": item_id, **item.dict()

• request body + 경로 매개변수 + 쿼리 매개변수

@app.put("/items/{item_id}")
async def create_item(item_id: int, item: Item, q: Union[str, None] = None):
    result = {"item_id": item_id, **item.dict()}
    if q:
        result.update({"q": q})
    return result

---

5. 퀴리 매개변수와 문자열 검증

⇒ parameter에 대한 추가 정보 제공할 수 있다.

@app.get("/itmes/")
async def read_items(q: Union[str, None] = None):
    result = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        result.update({"q" : q})
    return result

Union[str, None] 이라고 쓰면 q는 str아니면 None이라는 뜻 + None으로 기본값 존재 = 필수 아니라는 것을 FastAPI에서 알 수 있음

http://127.0.0.1:8000/itmes/?q=hello
{"items":[{"item_id":"Foo"},{"item_id":"Bar"}],"q":"hello"}

• 추가 validation

from typing import Union
from typing_extensions import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/itmes/")
async def read_items(q: Annotated[Union[str, None], Query(max_length=50)] = None):
    result = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        result.update({"q" : q})
    return result

• Annotated 는 매개변수에 메타데이터를 추가한다.
• Query 에서 max_length 를 지정함으로써 Query의 매개변수를 기준으로 들어오는 데이터를 걸러주기를 요청할 수 있다.
  • Query를 default value로 사용할 수 있다.
• Annotated 를 사용하는 방식이 권장된다,
  • Using Annotated is recommended instead of the default value in function parameters, it is better for multiple reasons. 🤓You could call that same function in other places without FastAPI, and it would work as expected. If there's a required parameter (without a default value), your editor will let you know with an error, Python will also complain if you run it without passing the required parameter.Because Annotated can have more than one metadata annotation, you could now even use the same function with other tools, like Typer. 🚀피
  • When you don't use Annotated and instead use the (old) default value style, if you call that function without FastAPI in other place, you have to remember to pass the arguments to the function for it to work correctly, otherwise the values will be different from what you expect (e.g. QueryInfo or something similar instead of str). And your editor won't complain, and Python won't complain running that function, only when the operations inside error out.
  • The default value of the function parameter is the actual default value, that's more intuitive with Python in general. 😌

필수 파라미터로 지정

q: str
q: Annotated[Union[str, None], Query(min_length=3)]
q: Annotated[str, Query(min_length=3)] = ...
q: Annotated[Union[str, None], Query(min_length=3)] = ... # None 허용, 필수
q: Annotated[str, Query(min_length=3)] = Required  # pydantic

리스트로 받기

async def read_items(q: Annotated[Union[List[str], None], Query()] = None):
    query_items = {"q": q}
    return query_items

http://127.0.0.1:8000/items/?q=hello&q=darling
{"q":["hello","darling"]}

• 기본값으로 리스트 주기도 가능

async def read_items(q: Annotated[Union[List[str], None], Query()] = ["hello", "darling"):
	query_items = {"q": q}
	return query_items

http://127.0.0.1:8000/items/
{"q":["hello","darling"]}

• List 대신 list 도 사용 가능

http://127.0.0.1:8000/items/
{"q":["hello","darling"]}

• list 내부 자료형이 뭔지는 검사하지 않음

추가 metadata

• title
• description
• Alias(별명)

async def read_items(q: Annotated[Union[str, None], Query(alias="item-query")] = None)

• 이러면 url에서 q가 아니라 item-query로 줘도 찰떡같이 알아듣는다.

6. 경로 매개변수와 숫자 검증

⇒ 쿼리 매개변수의 Query 와 같은 역할을 Path 가 해준다.

from typing import Union
from fastapi import FastAPI, Path, Query

app = FastAPI()

@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: Union[str, None] = Query(default=None, alias="item-query")
):
    result = {"item_id": item_id}
    if q:
        result.update({"q": q})
    return result

• 숫자 범위 검증

async def read_items(
    item_id: int = Path(title="The ID of the item to get", gt=0, lt=1000),
    q: Union[str, None] = Query(default=None, alias="item-query")
):
    result = {"item_id": item_id}
    if q:
        result.update({"q": q})
    return result

• gt = greater, lt = less then, ge = greater or equal, le = less than or equal
• 실수도 가능