🔨[개발] RESTful API

1. RESTful API란?

1.1. REST의 정의와 기본 개념

• REST(Representational State Transfer)는 월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식임.
• REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일.
• REST는 네트워크 상에서 Client와 Server 사이의 통신 방식 중 하나.
• REST는 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미함.
  → 즉, 자원(resource)의 표현(representation)에 의한 상태 전달임.

1.2. REST와 SOAP 비교

• SOAP(Simple Object Access Protocol)은 XML(eXtensible Markup Language)을 기반으로 하는 프로토콜로, RESTful API와 비교하여 복잡하고 무겁다는 특징이 있음.
• REST는 HTTP 프로토콜을 사용해 자원에 접근하는 방식을 따르며, 간단하고 직관적임.
• SOAP는 보안, 트랜잭션 등을 제공하지만 REST는 더 간결하고 성능이 우수함.

1.3. RESTful API의 특징

• 무상태성(Stateless): 서버는 클라이언트의 상태를 저장하지 않음.
• 자원 기반(URI): 각 자원은 고유한 URI로 식별됨.
• 표현: 자원의 상태는 JSON(Most), XML 등으로 표현됨.
• HTTP 메서드 활용: 자원에 대한 작업은 GET, POST, PUT, DELETE 등의 HTTP 메서드를 통해 수행됨.
• 요청과 응답 (Request and Response): 클라이언트는 요청을 보내고, 서버는 응답을 반환함. 요청에는 메서드, URI, 헤더, 바디 등이 포함되고, 응답에는 상태 코드, 헤더, 바디가 포함됨.

---

2. RESTful API의 구성 요소

2.1. 자원(Resource): URI

• 모든 자원은 URI(Uniform Resource Identifier) 혹은 URL(Uniform Resource Location)으로 식별됨.
• 각 자원은 고유한 URI를 통해 접근할 수 있음.
• e.g. /users는 모든 사용자 정보를 나타내고, /users/{id}는 특정 사용자의 정보를 나타냄.

2.2. 행위(Verb): HTTP 메서드

• POST(Create): 자원 생성
• GET(Read): 자원 조회
• PUT(Update): 자원 업데이트
• DELETE(Delete): 자원 삭제
• HEAD: Header 정보 조회

2.3 표현(Representation of Resource)

• Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보냄
• 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있음.
• JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적임.

---

3. RESTful API 설계 원칙

3.1. 간결하고 명확한 URI 설계

• RESTful API 설계에서 URI는 자원을 명확히 식별하고 의미 있는 방식으로 정의해야 함.
• /users와 같은 복잡하지 않고 직관적인 경로를 사용하는 것이 좋음.

3.2. HTTP 메서드의 적절한 사용

• HTTP 메서드는 자원에 대한 작업을 명확하게 정의하는 중요한 요소임.
• e.g. 데이터 조회는 GET, 데이터 생성은 POST, 업데이트는 PUT, 삭제는 DELETE를 사용함.

3.3. 상태 코드(State Codes)와 에러 처리

• RESTful API는 요청 처리 결과를 HTTP 상태 코드로 전달함.
• e.g. 200번대 코드는 성공, 400번대 코드는 클라이언트 오류, 500번대 코드는 서버 오류를 나타냄.

3.4. 필수 헤더(Header)와 인증(Authentication)

• RESTful API는 요청과 응답에 필요한 정보를 헤더에 담아 전달함.
• 또한, API의 보안을 위해 인증과 권한 부여를 적절히 구현해야 함.

---

4. FastAPI로 RESTful API 구현하기

4.1. FastAPI 소개 및 설치

• FastAPI는 Python을 사용한 고성능 웹 프레임워크로, RESTful API를 쉽고 빠르게 개발할 수 있도록 설계됨.
  • pip install fastapi[all]
• FastAPI 서버를 오픈하려면 WSGI (Web Server Gateway Interface)서버, 혹은 프록시 서버가 필요함
  • pip install uvicorn

WSGI (Web Server Gateway Interface)
WSGI는 Python 웹 애플리케이션과 웹 서버 간의 표준 인터페이스

• 동기 기반 웹 애플리케이션을 실행할 때 주로 사용됨.
• Flask나 Django와 같은 동기 애플리케이션에서 자주 사용됨.
• WSGI 서버는 애플리케이션의 요청을 받아 웹 서버가 처리할 수 있는 형태로 변환하여 전달함.
• Gunicorn이나 uWSGI 같은 서버가 WSGI 서버로 널리 사용됨.

프록시 서버 (Proxy Server)
프록시 서버는 클라이언트와 실제 서버 사이에서 요청과 응답을 중계하는 서버

• Nginx나 Apache와 같은 웹 서버가 주로 프록시 서버로 사용됨.
• 주요 역할:
  • 클라이언트의 요청을 실제 백엔드 서버로 전달.
  • 로드 밸런싱, 보안, SSL 종료, 캐싱 등의 작업을 처리.
  • 클라이언트와 서버 간의 트래픽을 관리하고 최적화함.

4.2. 첫 번째 API 작성

FastAPI를 이용해 간단한 API를 작성하는 예제

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI!"}

uvicorn main:app --reload

4.3. GET, POST, PUT, DELETE 예제

FastAPI는 HTTP 메서드를 쉽게 구현할 수 있도록 지원함.

• GET: /items로 GET 요청 시 아이템 리스트를 반환.
• POST: /items로 POST 요청 시 새로운 아이템을 추가.
• PUT: /items/{id}로 PUT 요청 시 특정 아이템을 업데이트.
• DELETE: /items/{id}로 DELETE 요청 시 특정 아이템을 삭제.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List

app = FastAPI()

# 아이템 모델 정의
class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

# 아이템 리스트 (임시 저장소)
items = []

# 1. GET: /items로 GET 요청 시 아이템 리스트를 반환
@app.get("/items", response_model=List[Item])
def get_items():
    return items

# 2. POST: /items로 POST 요청 시 새로운 아이템을 추가
@app.post("/items", response_model=Item)
def create_item(item: Item):
    items.append(item)
    return item

# 3. PUT: /items/{id}로 PUT 요청 시 특정 아이템을 업데이트
@app.put("/items/{item_id}", response_model=Item)
def update_item(item_id: int, item: Item):
    if item_id >= len(items) or item_id < 0:
        raise HTTPException(status_code=404, detail="Item not found")
    items[item_id] = item
    return item

# 4. DELETE: /items/{id}로 DELETE 요청 시 특정 아이템을 삭제
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    if item_id >= len(items) or item_id < 0:
        raise HTTPException(status_code=404, detail="Item not found")
    deleted_item = items.pop(item_id)
    return {"message": "Item deleted", "item": deleted_item}

uvicorn main:app --reload

4.4. 데이터 검증(Pydantic 모델 사용)

FastAPI는 Pydantic 모델을 사용해 요청 데이터를 검증할 수 있음.

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str = None

# 이 모델 클래스는 요청 본문에서 받은 데이터가 정확한 타입인지, 필수 값은 있는지, 각 값이 유효한지 검사

4.5. API 문서화(Swagger UI)

• FastAPI는 Swagger UI를 통해 API 문서를 자동으로 생성해줌.
• /docs 경로로 접근하면 API를 쉽게 테스트하고 문서화할 수 있음.

---

Flask로 RESTful API 구현하기

5.1. Flask 소개 및 설치

Flask는 간단하고 유연한 Python 웹 프레임워크로, RESTful API를 구축하는 데 많이 사용됨. pip install flask로 설치할 수 있음.

5.2. 가벼운 API 작성

Flask로 간단한 RESTful API를 작성하는 예제

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/")
def hello():
    return jsonify({"message": "Hello, Flask!"})

if __name__ == "__main__":
    app.run(debug=True)

python app.py

이제 서버가 켜졌고, http://127.0.0.1:5000에 접속하면,
아래와 같이 미리 만든 dict가 뜬다.

5.3. Flask-restful 확장 패키지 사용하기

Flask는 Flask-restful이라는 확장 모듈을 통해 RESTful API를 쉽게 작성할 수 있음.

from flask import Flask
from flask_restful import Api, Resource

app = Flask(__name__)
api = Api(app)

# 리소스 정의
class Item(Resource):
    def get(self, item_id):
        return {"item": item_id}

# API 리소스 등록
api.add_resource(Item, '/item/<int:item_id>')

if __name__ == "__main__":
    app.run(debug=True)

python app.py

이제 서버가 켜졌고, http://127.0.0.1:5000/item/1004로 접속하면,
아래와 같이 미리 만든 dict가 뜬다.

---

6. RESTful API 보안

6.1. 인증(Authentication)과 권한 부여(Authorization)

• RESTful API에서는 사용자의 인증과 권한 부여가 필수적임.
• JWT(JSON Web Token)를 사용하여 API의 인증을 처리함.
• 프로덕션 환경에서는 SSL 인증(Secure Sockets Layer) 또는 TLS 인증(Transport Layer Security)을 적용하는 것이 필요함

6.2. JWT(JSON Web Token)이란?

• JWT는 API에서 사용자 인증 정보를 안전하게 전달하는 방법임.
• JWT를 사용하면 세션을 서버에서 관리하지 않고도 사용자 인증을 처리할 수 있음.
• JWT는 헤더(Header), 페이로드(Payload), 서명(Signature) 세 부분으로 구성됨.

1. Header (헤더):

   • JWT의 첫 번째 부분은 헤더로, 토큰의 타입(일반적으로 JWT)과 서명 알고리즘(예: HMAC SHA256, RSA 등)을 지정.
   • e.g {"alg": "HS256", "typ": "JWT"}

2. Payload (페이로드):

   • 페이로드에는 전송할 정보가 들어 있음.

   • 이 정보는 클레임(claims)이라고 하며, 사용자가 인증을 받은 후 서버에서 어떤 정보가 필요한지 포함.

   • e.g. 사용자 ID, 역할(role), 만료 시간(expiration) 등이 포함될 수 있음

   • 클레임은 크게 세 가지로 분류:

     • 등록된 클레임(Registered claims): JWT에서 정의된 기본 클레임(예: sub, iat, exp 등)
     • 공개 클레임(Public claims): 시스템에서 자유롭게 사용할 수 있는 클레임
     • 비공개 클레임(Private claims): 두 시스템 간에 합의된 데이터

   • e.g. {"sub": "1234567890", "name": "John Doe", "iat": 1516239022}

3. Signature (서명):

   • 서명은 헤더와 페이로드가 변조되지 않았음을 확인하는 데 사용.
   • 서명은 header와 payload를 비밀 키(secret key)와 함께 서명 알고리즘을 사용해 암호화하여 생성
   • e.g. HMACSHA256(base64UrlEncode(header) + "." +base64UrlEncode(payload), secret_key)

6.3 JWT의 사용 흐름

1. 사용자가 로그인:

   • 사용자가 서버에 로그인할 때, 서버는 사용자의 인증 정보를 확인하고 JWT를 생성.
   • 이 JWT는 서버가 클라이언트에게 반환합니다.

2. JWT 저장:

   • 클라이언트는 받은 JWT를 저장하고, 이후 서버와의 통신에서 이 토큰을 HTTP 헤더에 포함하여 보냄

3. JWT 전송:

   • 클라이언트는 서버로 요청을 보낼 때 Authorization 헤더에 Bearer와 함께 JWT를 포함.
   • e.g. Authorization: Bearer <JWT>

4. 서버에서 JWT 검증:

   • 서버는 받은 JWT를 검증하여, 유효한 토큰인지, 변조되지 않았는지, 만료되지는 않았는지를 확인.
   • 유효한 토큰이라면 서버는 클라이언트의 요청을 처리합니다.

6.4. API Rate Limiting과 CORS 설정

• API의 남용을 방지하기 위해 Rate Limiting을 설정할 수 있음.
• 또한, CORS(Cross-Origin Resource Sharing)를 설정하여 특정 도메인만 API에 접근하도록 제한할 수 있음.

---