13장. REST API 와 FastAPI

HTTP 요청과 응답의 생김새

택배 상자에는 받는 주소와 "깨지기 쉬움" 같은 스티커가 붙고, 안에 물건이 들어 있습니다. 받는 쪽은 "잘 받았음"이나 "주소 불명으로 반송" 같은 답을 보냅니다. HTTP 요청도 주소와 메서드, 머리글(스티커), 본문(물건)으로 되어 있고, 응답은 상태 코드와 본문으로 돌아옵니다.

메서드와 주소, 머리글, 본문으로 된 요청이 가고, 상태 코드와 본문으로 된 응답이 돌아오는 네 단계 흐름도

1번 요청 줄에는 POST /predict 처럼 메서드와 주소가 있습니다. 2번 머리글에는 Content-Type: application/json 이나 API 키 같은 부가 정보가 있습니다. 3번 본문에는 보낼 JSON 이 있습니다. 4번 응답은 200 같은 상태 코드와 결과 JSON 으로 돌아옵니다. 여기서 택배 주소가 주소, 스티커가 머리글, 상자 속 물건이 본문, 반송 쪽지가 상태 코드입니다.

자주 보는 상태 코드

코드	뜻	이 장에서 나오는 때
200 OK	성공	예측을 돌려줄 때
201 Created	새로 만들었다	새 자원(주문 등)을 만들었을 때
400 Bad Request	요청이 잘못됐다	처리할 수 없는 요청
401 Unauthorized	누구인지 모른다	API 키나 토큰이 없거나 틀렸을 때
403 Forbidden	누구인지는 알지만 허락되지 않았다	역할에 없는 일을 하려 할 때
404 Not Found	그런 주소가 없다	없는 엔드포인트, 없는 자원
422 Unprocessable Content	꼴은 JSON 인데 값이 규칙에 어긋난다	FastAPI 의 입력 검사에 걸렸을 때
429 Too Many Requests	너무 자주 불렀다	정한 횟수를 넘었을 때(프로젝트)
500 Internal Server Error	서버 안에서 오류가 났다	코드의 버그, 모델 파일이 없을 때

상태 코드 찾아보기

Python

from http import HTTPStatus

# 표준 라이브러리에 상태 코드의 이름과 설명이 들어 있다
for code in (200, 401, 403, 422, 429):
    s = HTTPStatus(code)
    print(code, s.phrase)

코드에 나오는 함수

코드	쉬운 뜻
`from http import HTTPStatus`	표준 라이브러리 http 에 든 상태 코드 목록을 불러온다. 따로 설치하지 않아도 된다
`HTTPStatus(code)`	숫자로 그 상태 코드를 찾는다
`s.phrase`	phrase(짧은 구절)다. 상태 코드의 짧은 영어 이름이다

이 코드가 뜻하는 것

택배 반송 쪽지에 "3번"이라는 숫자만 적혀 있어도, 뒷면의 부호표를 보면 "주소 불명"이라는 뜻을 찾을 수 있습니다. 여기서 쪽지의 숫자가 상태 코드이고, 부호표가 HTTPStatus 입니다.

줄	하는 일	쉽게 말하면
`for code in (200, 401, ...)`	이 장에서 자주 볼 코드 다섯을 차례로 본다	쪽지 다섯 장
`s = HTTPStatus(code)`	숫자로 상태 코드를 찾는다	부호표에서 번호 찾기
`print(code, s.phrase)`	숫자와 이름을 함께 보인다	번호 옆의 뜻 읽기

실행하면 200 OK, 401 Unauthorized, 403 Forbidden, 422 Unprocessable Content, 429 Too Many Requests 가 한 줄씩 나옵니다. 위 표의 이름과 같습니다.

주의할 점

4xx 는 "부른 쪽이 고쳐야 할 오류", 5xx 는 "서버가 고쳐야 할 오류"입니다. 입력이 틀렸는데 500 을 돌려주면 부른 쪽은 무엇을 고칠지 모릅니다.
오류 응답에 서버 내부의 경로, 비밀번호, 쿼리 같은 정보를 그대로 넣지 않습니다. 공격자에게 힌트가 됩니다.