[FastAPI] FastAPI [2] Tutorial

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

Tutorial - User Guide - Intro - FastAPI

<FastAPI 공식문서 참조>

<first-steps 부터 시작>

 

 

1. Open API 와 OpenAPI 란

 Open API는 개방된 API라고 직관적으로 이해할 수 있다. 누구나 사용할 수 있도록 API의 endpoint가 개방되어있으면 OpenAPI이다. 예를 들어, 기상청의 단기 예보 조회 API, 우체국의 우편번호 API등이 있다. Public API(공공 API)라고도 부른다.

 

 OpenAPI, 위 용어와 공백 하나로 구분되는 이것은 위와 완전 다른 의미를 가지고 있다. 이는 RESTful API를 기존에 정의된 규칙에 맞게 API spec을 json등으로 표현하는 방식을 의미한다. 소스코드나 문서를 보지 않고 서비스를 이해할 수 있다는 장점이 있다.

 다시 말해, RESTful API 디자인에 대한 정의(; 명세; Specification) 표준이라고 생각하면 된다.

이전엔 Swagger 2.0과 같은 이름으로 불렸다가 현재 3.0버전에선 OpenAPI 3.0 Specification으로 불린다.

 

1-1. REST란?

 Representational State Transfer(REST)의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미한다.

 

즉, HTTP URI(Uniform Resource Identifier)를 통해 자원을 명시하고
HTTP Method(post, get, put, delete, patch 등)을 통해
해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다.

REST는 위처럼 자원, 자원에 대한 행위, 자원에 대한 행위의 내용으로 구성되어있다.

Create : POST ; 데이터 생성
Read : GET ; 데이터 조회
Update : PUT, PATCH ; 데이터 수정
Delete : DELETE ; 데이터 삭제

URI는 URL을 포함하는 개념이다. 헷갈리지 말자.

 

1-2. REST API 란?

 REST의 원리를 따르는 API를 의미한다.

• 설계 예시
  • URI는 명사와 소문자를 위주로 작성해야 한다.
    • Good ex) https://google.com/run
    • Bad ex) https://google/com/running
  • 마지막에 슬래시(/)를 포함하지 않는다.
    • Good ex) https://google.com/run
    • Bad ex) https://google/com/run/
  • 언더바 대신 하이픈을 사용한다.
    • Good ex) https://300-29-1.tistory.com
    • Bad ex) https://300_29_1.tistory.com
  • 파일 확장자는 URI에 포함하지 않는다.
    • Good ex) https://300-29-1.tistory.com/my-photo
    • Bad ex) https://300_29_1.tistory.com//my-photo.png
  • 행위를 포함하지 않는다.
    • Good ex) https://300-29-1.tistory.com/my-photo
    • Bad ex) https://300_29_1.tistory.com/delete/my-photo

 REST를 사용하며 REST API의 설계 규칙을 올바르게 지킨 시스템을 RESTful하다고 할 수 있다.

 

 

2. OpenAPI 표준

2-1. Scheme (스키마)

 스키마는 무언가의 정의 또는 설명이다. 무언가를 구현하는 소스코드가 아니라 추상적인 설명일 뿐이다.

 

• API 스키마 : OpenAPI는 API의 스키마를 어떻게 정의하는지 지시하는 일종의 규격이다. 이는 API 경로, 가능한 매개변수 등을 포함한다.
• 데이터 스키마 : 스키마는 JSON처럼 어떤 데이터의 형태를 나타낼 수도 있다. 이는 JSON 속성, 가지고있는 데이터 타입등을 명세한다.
• OpenAPI와 JSON 스키마
  • OpenAPI의 스키마에는 API의 스키마 및 JSON 스키마를 사용하여 보내고 받은 데이터의 스키마도 포함한다.

 

3. Path operation

 여기서 경로(path)라 함은 URL의 첫  /  부터 마지막 부분까지를 의미한다.

만약, URL이 아래와 같다면,

https://example.com/items/foo

경로, path는 다음과 같다.

/items/foo

* 일반적으로 path는 endpoint 혹은 route(라우트)로도 불린다.

 

3-1. Path Parameters

 파이썬 포맷 문자열이 사용하는 동일한 문법으로 매개변수 혹은 변수를 경로에 선언할 수 있다.

 

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

이 함수를 넣은 후 http://127.0.0.1:8000/items/yeah_im_item 을 입력하면 아래 응답을 볼 수 있다.

{"item_id":"yeah_im_item"}

 혹은 매개변수에 타입을 지정해 줄 수도 있다.

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

이 기능은 함수 내에서 오류 검사, 자동완성등을 지원한다.

이 함수를 실행하면 {"item_id":3}이 출력되는데, 이때 함수가 받은 값은 문자열 3이 아닌 int형 3이다.

즉, 타입 선언시 FastAPI는 자동으로 해당 요청을 parsing 한다.

 

* 파싱 : 인터넷에 주어진 정보를 내가 원하는대로 가공하여 서버에서 원하는 때 불러올 수 있도록 하는 것

 

이때 int형이 아닌 다른 자료형을 집어넣는다면,

{"detail":[{"loc":["path","item_id"],"msg":"value is not a valid integer","type":"type_error.integer"}]}

이라는 오류를 확인 할 수 있다.

해당 오류는 통과하지 못한 지점도 정확히 명시한다. 디버깅할 때 매우 유용하다.

 

3-2. Order matters

 Path Operation를 만들 때, fixed path(고정 경로)를 가지고 있는 인자들을 받을 수 있다.

예를 들어, /users/me 처럼 현재 사용자의 데이터를 가져온다고 하자.

다른 상황으로, 사용자 ID를 이용해 해당 특정 사용자의 정보를 가져오는 /users/{user_id} 도 있다.

이 때 우선순위의 문제가 발생할 수 있는데, 경로 동작은 순차적으로 평가되기 때문에 /users/{user_id} 이전에 /users/me 를 먼저 선언해야 한다.

 

3-3. Predenfined values(사전 정의 값)

 이미 존재하는 Path Operation에 대해, 파이썬 표준 Enum을 이용해 path parameter value를 미리 정의할 수 있다.

 

• Enum 클래스 생성
  • Enum을 import 후 str과 Enum을 상속하는 서브 클래스를 만든다.
    • 이를 통해 API문서는 값이 string 형이어야 하는 것을 알게 되고, 제대로 렌더링 할 수 있게된다.
    • 고정값으로 사용할 수 있는 유효한 클래스 속성(attribute)를 만든다.

from enum import Enum

from fastapi import FastAPI

app = FastAPI()

@app.get("models/{model_name}")
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"}

model_name.value를 통해 실제 값을 가져올 수 있다.

 

 

 

 

4. Query Parameters

특정 함수 매개변수 - 경로 매개변수의 일부가 아닐 때, FastAPI는 이를 "쿼리" 매개변수로 자동 해석한다.

* 쿼리는 URL에서  ? 이후에 나오고  & 로 구분되는, key - value 쌍의 집합이다.

# fake_items_db
fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]

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

쿼리 매개변수는 URL의 일부라 당연히 문자열이 된다. 그러나 자료형을 지정해주면 해당 타입으로 변환하고, 검증한다.해당 예제에서 

 http://127.0.0.1:8000/items/ 로 이동하는 것은  http://127.0.0.1:8000/items/?skip=0&limit=10로 이동한 것과 같다.

 

* parameter를 None으로 초기화 하여 선택적 매개변수로도 사용할 수 있다.

* 초기화를 하지 않으면 해당 parameter는 필수 parameter가 된다. error로 field required라는 메세지를 반환한다.

 해당 예제에서

Union[str, None]

 

이라는 자료형이 등장하는데, Union은 editor가 코드에서 오류를 찾아낼 수 있게 도와준다.

 

* 쿼리형 매개변수의 bool 타입은 1, True, true를 포함한 모든 string의 변형을  True 로 인식한다. 그 외는  False 로 인식한다.

 

4-1. 다중 경로/쿼리 매개변수

 FastAPI는 각 매개변수들을 이름으로 식별, 구분한다.

# 다중 매개변수
@app.get("/users/{user_id}/items/{item_id}")
def read_user_item(user_id: int, item_id: str, q: Union[str, None] = None,
                   short: bool = False):
    item = {"item_id": item_id, "owner_id": user_id}
    if q:
        item.update({"q": q})
        if not short:
            item.update({"description": "This is an amazing item that has a long descriptoin."})
    return item

 

 

 

5. 참조

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

https://gruuuuu.github.io/programming/openapi/

https://khj93.tistory.com/entry/%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-REST-API%EB%9E%80-REST-RESTful%EC%9D%B4%EB%9E%80

https://khj93.tistory.com/entry/%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-REST-API%EB%9E%80-REST-RESTful%EC%9D%B4%EB%9E%80