아토믹데브_5_파이썬과 MSA 기반의 기업용 솔루션 개발 실무

API 설계 및 RESTful 서비스

RESTful 서비스는 현대 웹 애플리케이션에서 가장 많이 사용되는 아키텍처 스타일 중 하나로, 클라이언트와 서버 간의 통신을 간결하고 효율적으로 수행할 수 있도록 합니다. 이 섹션에서는 REST API의 개념과 설계 방법을 소개하고, OpenAPI/Swagger를 사용해 API를 문서화하는 방법을 살펴봅니다.

1. REST API의 개념과 설계 방법

**REST (Representational State Transfer)**는 웹 서비스 설계를 위한 아키텍처 스타일로, 자원(Resource)을 정의하고 자원에 대한 표준적인 HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 CRUD(Create, Read, Update, Delete) 작업을 수행합니다.

REST API 설계의 주요 원칙:

1. 자원(Resource) 기반: 모든 것은 자원으로 취급됩니다. 각 자원은 URI(Uniform Resource Identifier)로 고유하게 식별됩니다.
2. HTTP 메서드 활용: 자원에 대해 수행할 작업은 HTTP 메서드를 사용하여 정의합니다.
   • GET: 자원의 조회
   • POST: 자원의 생성
   • PUT: 자원의 전체 수정
   • PATCH: 자원의 부분 수정
   • DELETE: 자원의 삭제
3. 무상태(Stateless): 모든 요청은 독립적이며, 서버는 이전 요청에 대한 정보를 저장하지 않습니다.
4. 표현(Representation): 자원은 JSON, XML 등 다양한 형태로 표현될 수 있으며, 클라이언트는 서버에서 자원의 표현을 요청합니다.
5. 표준화된 URI: 자원에 접근하기 위한 URI는 명확하고 일관된 구조를 가져야 합니다.

예시 코드: Flask로 REST API 설계

from flask import Flask, request, jsonify

app = Flask(__name__)

# 예시 자원: 책 목록
books = [
    {'id': 1, 'title': '1984', 'author': 'George Orwell'},
    {'id': 2, 'title': 'To Kill a Mockingbird', 'author': 'Harper Lee'}
]

# GET 메서드: 모든 책 정보 조회
@app.route('/books', methods=['GET'])
def get_books():
    return jsonify(books)

# GET 메서드: 특정 책 정보 조회
@app.route('/books/<int:book_id>', methods=['GET'])
def get_book(book_id):
    book = next((book for book in books if book['id'] == book_id), None)
    if book:
        return jsonify(book)
    else:
        return jsonify({'error': 'Book not found'}), 404

# POST 메서드: 새로운 책 추가
@app.route('/books', methods=['POST'])
def add_book():
    new_book = request.get_json()
    new_book['id'] = len(books) + 1
    books.append(new_book)
    return jsonify(new_book), 201

# PUT 메서드: 책 정보 수정
@app.route('/books/<int:book_id>', methods=['PUT'])
def update_book(book_id):
    book = next((book for book in books if book['id'] == book_id), None)
    if book:
        updated_data = request.get_json()
        book.update(updated_data)
        return jsonify(book)
    else:
        return jsonify({'error': 'Book not found'}), 404

# DELETE 메서드: 책 삭제
@app.route('/books/<int:book_id>', methods=['DELETE'])
def delete_book(book_id):
    global books
    books = [book for book in books if book['id'] != book_id]
    return '', 204

if __name__ == '__main__':
    app.run(port=5000)

위 코드는 Flask 프레임워크를 사용해 RESTful API를 설계하는 예시입니다. 책 목록을 관리하는 API를 구축했으며, 각 HTTP 메서드를 사용해 자원을 생성, 조회, 수정, 삭제할 수 있습니다.

2. OpenAPI/Swagger를 활용한 API 문서화

OpenAPI는 RESTful API를 기술하고 문서화하기 위한 표준 명세입니다. Swagger는 OpenAPI 사양을 기반으로 하는 도구로, API 문서를 자동으로 생성하고, 인터랙티브 API 콘솔을 제공하여 API를 테스트할 수 있습니다.

설치 및 설정

Swagger와 함께 사용하기 위해 Flask에서 flask-swagger-ui와 flasgger 라이브러리를 사용할 수 있습니다.

pip install flasgger
pip install flask-swagger-ui

예시 코드: Flask + Swagger를 사용한 API 문서화

from flask import Flask, request, jsonify
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

books = [
    {'id': 1, 'title': '1984', 'author': 'George Orwell'},
    {'id': 2, 'title': 'To Kill a Mockingbird', 'author': 'Harper Lee'}
]

@app.route('/books', methods=['GET'])
def get_books():
    """
    모든 책 정보 조회
    ---
    responses:
      200:
        description: 책 목록을 반환합니다.
        schema:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                description: 책 ID
              title:
                type: string
                description: 책 제목
              author:
                type: string
                description: 저자 이름
    """
    return jsonify(books)

@app.route('/books/<int:book_id>', methods=['GET'])
def get_book(book_id):
    """
    특정 책 정보 조회
    ---
    parameters:
      - name: book_id
        in: path
        type: integer
        required: true
        description: 책 ID
    responses:
      200:
        description: 책 정보를 반환합니다.
      404:
        description: 책을 찾을 수 없습니다.
    """
    book = next((book for book in books if book['id'] == book_id), None)
    if book:
        return jsonify(book)
    else:
        return jsonify({'error': 'Book not found'}), 404

@app.route('/books', methods=['POST'])
def add_book():
    """
    새로운 책 추가
    ---
    parameters:
      - name: body
        in: body
        required: true
        schema:
          type: object
          properties:
            title:
              type: string
            author:
              type: string
    responses:
      201:
        description: 새로 추가된 책 정보를 반환합니다.
    """
    new_book = request.get_json()
    new_book['id'] = len(books) + 1
    books.append(new_book)
    return jsonify(new_book), 201

if __name__ == '__main__':
    app.run(port=5000)

 

Swagger UI 사용하기

위 코드에서 Swagger 객체를 Flask 앱에 추가하면, /apidocs 경로에서 자동으로 생성된 Swagger UI를 통해 API 문서를 볼 수 있습니다.

• Swagger UI 경로: http://localhost:5000/apidocs
• 이 UI를 통해 API의 모든 엔드포인트를 탐색하고, 샘플 요청을 직접 실행해 볼 수 있습니다.

요약

• REST API의 개념: 자원을 기반으로 HTTP 메서드를 통해 CRUD 작업을 수행하는 웹 서비스 아키텍처 스타일입니다.
• REST API 설계: 명확한 URI 구조와 HTTP 메서드를 사용해 서비스의 각 기능을 설계합니다.
• OpenAPI/Swagger: API를 명세하고 문서화하며, Swagger UI를 통해 인터랙티브한 API 테스트 환경을 제공합니다.

이러한 설계를 통해 개발자는 API의 기능을 쉽게 이해하고 사용할 수 있으며, OpenAPI/Swagger를 통해 API의 정확한 문서화를 보장할 수 있습니다.