HTTP 메서드 결정표 — 작업의 의미에서 메서드까지

# Code review 나 설계 논의용 'method picker' helper
from dataclasses import dataclass

@dataclass
class Operation:
    changes_state: bool
    target_uri_known: bool
    sends_full_resource: bool
    is_removal: bool
    has_natural_target: bool

def pick_method(op: Operation) -> str:
    if not op.changes_state:
        return 'GET (존재 체크엔 HEAD, 발견엔 OPTIONS)'
    if op.is_removal:
        return 'DELETE'
    if not op.has_natural_target:
        return 'Action URI 에 POST (예: POST /resource/{id}/action)'
    if not op.target_uri_known:
        return 'Collection 에 POST (server 가 ID 할당, 201 + Location 돌려줌)'
    if op.sends_full_resource:
        return 'PUT (idempotent — 전체 교체)'
    return 'PATCH (patch format 이 보장할 때만 idempotent)'

# 예 걸어보기
print(pick_method(Operation(changes_state=False, target_uri_known=True,
                            sends_full_resource=False, is_removal=False,
                            has_natural_target=True)))
# GET (존재 체크엔 HEAD, 발견엔 OPTIONS)

print(pick_method(Operation(changes_state=True, target_uri_known=False,
                            sends_full_resource=False, is_removal=False,
                            has_natural_target=True)))
# Collection 에 POST (server 가 ID 할당, 201 + Location 돌려줌)

# cwkPippa-스타일 FastAPI route — 각 method 선택이 의도적
from fastapi import FastAPI, APIRouter, status

app = FastAPI()
conversations = APIRouter(prefix='/api/conversations')

@conversations.get('/{cid}')
async def read_conversation(cid: str):
    # State 변경 없음, target URI 알려짐 → GET
    return await load_from_db(cid)

@conversations.post('', status_code=status.HTTP_201_CREATED)
async def create_conversation():
    # Server 가 ID 할당; 201 + Location 돌려줌
    new_id = await create_in_db()
    return {'id': new_id, 'location': f'/api/conversations/{new_id}'}

@conversations.put('/{cid}/title')
async def rename_conversation(cid: str, payload: dict):
    # Idempotent: 같은 title → 같은 state. PUT 이 맞음.
    await update_title(cid, payload['title'])
    return {'id': cid, 'title': payload['title']}

@conversations.patch('/{cid}')
async def update_conversation(cid: str, payload: dict):
    # 부분 update: payload 가 필드의 어느 부분집합이든 가질 수 있음. PATCH.
    return await apply_patch(cid, payload)

@conversations.delete('/{cid}', status_code=status.HTTP_204_NO_CONTENT)
async def delete_conversation(cid: str):
    await delete_from_db(cid)  # DELETE — idempotent

@conversations.post('/{cid}/finalize', status_code=status.HTTP_202_ACCEPTED)
async def finalize_council(cid: str):
    # Side effect 있는 command/action, idempotent 아님 — POST
    job_id = await enqueue_finalize(cid)
    return {'job_id': job_id, 'poll': f'/api/jobs/{job_id}'}