[FastAPI] FastAPI [1] - 공식 문서 정리 및 예제 실습

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

FastAPI

<FastAPI 공식문서 참조>

 

1. FastAPI란?

FastAPI는 Python3.6+의 API를 빌드하기 위한 웹 프레임워크이다.

 

주 특징으로:

빠르다(성능 및 코드 작성)(비동기 동작).

직관적이다.

쉽다.

짧다.

Robust 하다.

표준 기반되어있다.

API문서를 자동 생성한다.

 

기존 파이썬 웹개발에 사용되던 Flask와 Django의 사이를 비집고 들어온 프레임워크이다.

 

2. FastAPI 설치

< IDE는 VSCODE를 사용 >

 

1) install fastapi

pip3 install fastapi

 

2) install uvicorn

pip3 install uvicorn[standard]

 

● uvicorn 이란?

  uvicorn은 async/await를 기반한 비동기 프로그래밍 지원하는 ASGI 이다. 실행 결과를 확인하기 위한 용도로 설치한다.

● ASGI 란?

  ASGI는 비동기요청을 처리하기 위해 WSGI를 개선한 인터페이스이다. 서버로 uvicorn을 많이 사용한다.

● WSGI 란?

  WSGI, Web Server Gateway Interface는 파이썬에서 사용되는 인터페이스다. 서버는 이를 통해 사용자(클라이언트)의 요청을 Callable object인 함수나 객체로 처리하여 요청에 대한 정보와 Callback함수를 전달해준다. 이를 받은 app.은 이 요청을 처리하고 Callback 함수를 실행한다. 이런 인터페이스를 구현하는 서버와 app.을 WSGI compatible, 특히 어플리케이션을 WSGI application이라고 한다.

● CGI 란?

  서버와 사용자가, 로그인이나 회원가입 요청과 같이 동적인 정보를 주고받는 과정의 처리를 위한 인터페이스이다.

서버와 애플리케이션 언어마다 각기 다르기 때문에 이를 공통으로 표준화한 인터페이스이다.

 CGI는 요청이 들어올때마다 애플리케이션 프로세스를 다시 실행해야한다는 단점이 있다. 이러한 단점을 보완하기 위해 WSGI를 고안하였다.

● 동기/비동기 란?

  동기 방식은 하나의 작업이 완료된 후 작업을 진행하는 방식이다.

  비동기 방식은 하나의 작업이 진행되는 중 다른 작업도 진행할 수 있는 방식이다.

 

3. FastAPI 사용

<공식문서의 예제 참조>

[ 예제 ]

# main.py
from typing import Union

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():                  # func name
    return {"Hello" : "World"}    # return json

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

main.py 파일 작성 - 저장 이후 bash에 다음 코드를 입력하여 서버를 실행한다.

uvicorn main:app --reload

터미널 종료시 서버도 자동으로 종료된다.

# note
main : main.py 파일(파이썬 "모듈")
app : main.py 내부 app = FastAPI()코드에서 만들어진 객체
--reload : 코드 변경이후 서버 재시작하기, 개발환경에서만 사용

 

이후 웹사이트에  http://127.0.0.1:8000/items/5?q=somequery

혹은 localhost:8000/items/5?q=somequery 를 입력하여 확인해본다(localhost만 가능). Django와 같이 기본 포트가 8000이다.

 

{"item_id": 5, "q": "somequery"} 의 JSON 응답을 볼 수 있다.

 

벌써 하나의 API를 만들었다!

● 경로  /  및  /items/{item_id}  에서 HTTP 요청 받기( 단순 '/' 는 root )

● 두 경로 모두  get  연산을 받는다(get연산은 http 메소드이다).

● 경로  /items/{item_id} 는 int type item_id와 str type q를 가지고 있다..

 

 

각각의 메소드는 다음의 의미를 가지고 있다.

• POST: 데이터를 생성.
• GET: 데이터를 읽기.
• PUT: 데이터를 업데이트.
• DELETE: 데이터를 삭제.

OpenAPI에서는 각 HTTP 메소드들을 "동작"이라고 부른다.

그래서 FastAPI 공식문서도 각 메소드들을 "동작"이라고도 부른다.

 

 

다음과 같은 파이썬 함수는 :

@app.get("/")
def read_root():                  # func name
    return {"Hello" : "World"}    # return json

 GET  동작을 사용하며 URL " /  "에 대한 요청을 받을 때마다 FastAPI에 의해 호출된다.

 

 

[ 예제 심화 ]

 PUT  요청의 Body를 받기 위해 를  main.py  를 수정한다.

Pydantic을 이용해 파이썬 표준 타입으로 본문을 선언한다.

● Pydantic 이란?

  출력모델의 유형과 제약 조건을 보장하는 parsing 라이브러리이다. 타입이 다른 데이터가 매핑되도 동일하게 parsing해준다. parsing이 불가능한 데이터가 들어왔을 경우 error를 발생시킨다. Data model을 정의할 수 있는 simple sintax다.

BaseModel class에서 상속된 class내에서 데이터를 정의할 수 있다.

# main.py
from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    is_offer: Union[bool, None] = None

@app.get("/")
def read_root():                  # func name
    return {"Hello" : "World"}    # return json

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

@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    return {"item_name": item.name, "item_id": item_id}

이 때 FastAPI는

• GET 및 PUT 요청에 item_id가 경로에 있는지 & int type인지 검증한다.
  • 그렇지 않다면 명확한 error를 볼 수 있다.
• GET 요청에 q라는 선택적 쿼리 매개변수가 검사된다.
  • q = None으로 선언되었기 때문에 이는 선택적이다.
• /items/{item_id}로의 put 요청은 본문을 JSON으로 읽는다.
  • item이 Item type이기 때문에, name을 필수 속성으로 갖고 str형인지 검사, price를 필수 속성으로 갖고 float형인지 검사한다.
  • 선택적 속성인 is_offer를 bool 형인지 검사한다. 
• JSON을 변환하거나 JSON으로 변환하는 것을 자동화한다.

 

 

...이후 변경사항을 저장하면 서버가 자동으로 reloading 한다.

이후 ~/docs로 넘어가면

처럼 put 메소드가 추가된 것을 확인할 수 있다.

Try it out - Execute를 통해 직접 테스트해 볼 수도 있다.

4. Interactive API docs

http://127.0.0.1:8000/docs 로 이동하면 자동 대화형 API문서를 볼 수 있다(Swagger UI를 제공한다는데 아직 잘 모른다).

http://127.0.0.1:8000/redoc 로 이동시 다른(Alternative) API문서를 볼 수 있다.

 

5. 요약

parameter type, parameter body등을 parameter로 한 번에 선언했다.이를 현대 표준 파이썬 타입으로 실행했다.새로운 문법과 특정 라이브러리의 메소드, 클래스 등을 배울 필요가 없다.단지 표준 Python 3.6+ 밖에 없다.

 

int는

item_id: int

좀 더 복잡한 Item 모델은

item: Item

 

FastAPI를 통해

• 데이터 검증
• 입력 데이터 변환
• 출력 데이터 변환
• 자동 API 문서 2개(Swagger UI., ReDoc.)

를 사용할 수 있다.

 

6. 참고

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

https://www.youtube.com/watch?v=ZqSpl0Ic8ik