resource-oriented-design

📌 구글한테 배우는 리소스 오리엔티드 디자인⚑

1. 구글의 API 디자인 철학
   • 구글은 API 디자인 가이드라인에 진심이며, 특히 외부에 공개하는 퍼블릭 HTTP API는 신중하게 설계한다.
   • API는 한 번 공개되면 수정이 어렵기 때문에 신중한 설계가 필요하다.
2. 리소스 오리엔티드 디자인 vs. 액션 오리엔티드 디자인
   • 액션 오리엔티드 디자인: 특정 동작(예: 회원가입)을 함수처럼 정의하여 signup() 같은 메소드를 만든다.
   • 리소스 오리엔티드 디자인: HTTP 메소드(GET, POST, PATCH, DELETE)를 활용하여 POST /persons 형태로 리소스를 조작한다.
   • 리소스 오리엔티드 디자인은 직관적이며 표준화된 방식으로 API를 설계할 수 있다.
3. 리소스 오리엔티드 디자인의 핵심 원칙
   • API가 처리할 리소스(Resource) 를 정의한다.
   • 리소스 간의 관계(Relationships) 를 명확히 한다.
   • 리소스가 가지는 필드(Fields) 를 결정한다.
   • 리소스에서 지원할 HTTP 메소드(Methods) 를 정의한다.
4. 구글의 API 설계 접근 방식
   • 내부적으로 수천 개의 API를 운영하며, 인터널 API(RPC 기반)는 보통 액션 오리엔티드 방식을 많이 사용한다.
   • 하지만 액션 오리엔티드는 확장성이 낮고, 중복된 기능이 많아지며, 유지보수가 어려워지는 문제가 있다.
   • 이를 해결하기 위해 리소스 오리엔티드 디자인을 내부 API에도 적용하려는 시도를 하고 있다.
5. 결론
   • 리소스 오리엔티드 디자인은 API를 일관되고 유지보수하기 쉽게 만든다.
   • 구글은 내부 API에서도 이 방식을 적용하려는 노력을 기울이고 있다.

📌 실전 API 디자인 강의 | 포토 서비스 만들기 실습 - 요약⚑

1. API 설계 원칙
   • Create, Read, Update, Delete 기능을 표준 HTTP 메소드(GET, POST, PATCH, DELETE)로 구현해야 한다.
   • 요청(Request) 및 응답(Response) 네이밍은 일관되게 유지해야 하며, CreateResourceRequest, ResourceResponse 같은 명명 규칙을 따른다.
2. 리소스 및 데이터 모델 정의
   • 서비스 개요: 사용자가 사진(포토)을 업로드하고, 앨범을 생성 및 관리할 수 있는 API 설계.
   • 리소스 스키마 설계:
     • Storage Model: 데이터베이스에 저장되는 내부 모델.
     • Wire Model: 클라이언트와 서버가 주고받는 API 모델.
     • Storage Model과 Wire Model은 처음부터 분리해야 하며, ID 필드는 항상 String으로 정의하는 것이 구글 API 디자인 가이드라인의 베스트 프랙티스.
3. API 메소드 설계 원칙
   • 사진 업로드(Create Photo)
     • POST /photos 요청 시, CreatePhotoRequest와 Photo를 전달.
     • 부모 리소스(parent)를 포함하여 계층 구조를 명확하게 정의.
     • 응답(Response)은 Photo 객체만 반환하고, 부가적인 정보를 포함하지 않도록 제한.
   • 사용자의 모든 사진 조회(List Photos)
     • GET /photos 요청 시, ListPhotosRequest와 ListPhotosResponse를 사용.
     • 페이지네이션(Pagination) 필수 지원 (클라이언트가 대량 데이터를 처리하는 방식 유지).
   • 단일 사진 조회(Get Photo)
     • GET /photos/{photo_id} 요청 시, 특정 사진을 반환.
     • 구글 API 디자인 가이드에서는 name 필드를 ID로 사용하는 것을 권장.
4. API 디자인 시 고려할 점
   • API의 확장성과 유지보수를 위해 처음부터 Storage Model과 Wire Model을 분리해야 한다.
   • 페이지네이션 지원은 필수, 초기에 필요하지 않더라도 추가하지 않으면 클라이언트 코드 변경 없이 도입하기 어렵다.
   • 응답(Response)에 불필요한 정보를 포함하지 않도록 주의하여, API의 기능을 단순하고 명확하게 유지해야 한다.
   • API가 한 번 공개되면 쉽게 변경할 수 없으므로 Backward Compatibility를 유지하는 것이 중요하다.

✅ 결론

구글 API 디자인 가이드라인을 따르면, 유지보수성과 확장성을 고려한 API를 설계할 수 있으며, 클라이언트가 API를 안정적으로 사용할 수 있도록 도울 수 있다.

class PhotoAlbumStorageModel:
    def __init__(self, id: int, name: str, shared_users: list[int], created_at: int):
        self.id = id  # Integer ID (DB 저장 최적화)
        self.name = name
        self.shared_users = shared_users  # 유저 ID 리스트 (정수 타입)
        self.created_at = created_at  # UNIX Timestamp (DB 효율성 고려)

from pydantic import BaseModel
from typing import List

class PhotoAlbumWireModel(BaseModel):
    id: str  # ID는 항상 String으로 변환
    name: str
    shared_users: List[str]  # User ID도 String으로 변환 (UUID 또는 Email 가능)
    created_at: str  # ISO 8601 날짜 형식 ("2024-02-10T12:34:56Z")

def convert_storage_to_wire(storage_model: PhotoAlbumStorageModel) -> PhotoAlbumWireModel:
    return PhotoAlbumWireModel(
        id=str(storage_model.id),  # 정수 ID → 문자열 ID 변환
        name=storage_model.name,
        shared_users=[str(uid) for uid in storage_model.shared_users],  # 정수 리스트 → 문자열 리스트 변환
        created_at="2024-02-10T12:34:56Z"  # UNIX Timestamp → ISO 8601 변환 (예제)
    )

PUT /users/123
Content-Type: application/json

{
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30
}

{
    "name": "Alice",
    "email": "alice@example.com",
    "age": 25,
    "address": "New York"
}

{
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30
    // "address" 필드는 삭제됨! (데이터 손실 가능)
}

PATCH /users/123
Content-Type: application/json

{
    "age": 30
}

{
    "name": "Alice",
    "email": "alice@example.com",
    "age": 25,
    "address": "New York"
}

{
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30,   // 나이만 업데이트됨
    "address": "New York" // 나머지는 그대로 유지됨
}

📌 실전 API 디자인 강의 | 포토 서비스 만들기 실습 - 2편 - 요약⚑

1. 리소스 오리엔티드 디자인의 장단점
   • 장점: 일관된 스탠다드 메소드를 활용하여 API를 관리하기 쉬움.
   • 단점: 다양한 유즈케이스를 하나의 메소드로 처리해야 하므로 데이터 페이로드가 비효율적일 수 있음.
2. 기본적인 API 설계 원칙
   • 리소스 삭제(Delete Photo):
     • DELETE /photos/{photo_id}
     • 아이디만 전달하면 되고, 응답(Response)은 비어 있어야 함.
   • 새로운 앨범 생성(Create Album):
     • 기존 포토 생성과 거의 동일한 패턴을 따름.
   • 일관된 API 설계의 장점:
     • 여러 개의 API가 동일한 패턴을 따르므로 코드 자동 생성(Code Generation)이 가능.
     • 구글 내부에서는 리소스 이름만 바꾸고 코드 제너레이션을 활용하여 API를 자동으로 생성함.
3. 앨범 내 사진 추가 및 제거 (Update Photo Album)
   • 문제점:
     • 액션 오리엔티드 방식에서는 AddPhotosToAlbum, RemovePhotosFromAlbum, RenameAlbum 같은 개별 메소드가 생성됨.
     • 리소스 오리엔티드 방식에서는 하나의 Update 메소드가 여러 유즈케이스를 처리해야 하므로 데이터 페이로드가 증가할 수 있음.
   • 해결책: 필드 마스크(Field Mask) 사용
     • 필드 마스크를 활용하면 업데이트할 필드만 선택적으로 변경 가능.
     • 예를 들어, 앨범 이름만 변경할 경우 "field_mask": "album_name"을 설정하여 해당 필드만 업데이트.
     • PUT(전체 변경) vs PATCH(부분 변경)의 개념과 유사.
4. 특정 필드 포함 여부 설정 (텍스트 디텍션 포함/제외)
   • 텍스트 디텍션(Textraction) 기능을 API 응답에 포함할지 여부를 선택할 수 있도록 설계.
   • 기본 방식:
     • GET /photos/{photo_id} 요청 시, 모든 필드를 포함한 응답 반환.
   • 문제점:
     • 텍스트 디텍션이 비용이 높은 연산이므로 항상 포함하는 것은 비효율적.
   • 해결책: View Enum 활용
     • 필드 마스크(Field Mask)*를 활용할 수도 있으나, API 사용성이 떨어짐 (제외할 필드를 제외하는 방식이 아닌, 포함할 필드를 지정하는 방식).
     • 대신 View Enum을 사용하여 미리 정의된 응답 형태를 제공.
     • 예시:
       • "view": "BASIC" → 텍스트 디텍션 제외
       • "view": "WITH_TEXT_DETECTION" → 텍스트 디텍션 포함
5. 결론
   • 리소스 오리엔티드 디자인을 따르면 API의 일관성을 유지하고, 코드 자동 생성 및 유지보수가 쉬워진다.
   • 필드 마스크(Field Mask)와 View Enum을 활용하면 데이터 페이로드 최적화 가능.
   • API 설계를 처음부터 표준화하면 확장성과 유지보수성이 향상된다.

참고 자료⚑

• https://www.youtube.com/watch?v=8lERCj-YRvI
• https://www.youtube.com/watch?v=6_mtlkt0MJE
• https://www.youtube.com/watch?v=5lRcJKo6R2s