피드로 돌아가기
Dev.toBackend
원문 읽기
REST API Discoverability 개선을 통한 Media Upload 복구 메커니즘 설계
How I Submitted My First WordPress Core Patch (And What I Learned)
AI 요약
Context
WordPress Media Upload 중 서버 리소스 부족으로 인한 프로세스 중단 시, 클라이언트는 X-WP-Upload-Attachment-ID 헤더를 통해 Attachment ID만 수신하는 구조. 재처리를 위한 /post-process 엔드포인트의 위치를 알려주는 Link 헤더의 부재로 인해 클라이언트가 URL을 하드코딩하거나 추측해야 하는 REST API 원칙 위배 상황 발생.
Technical Solution
- create_item() 내 raw header() 호출 시점과 $response 객체 생성 시점의 분리 분석을 통한 사이드 이펙트 제거
- Response 객체 생성 후 Location 헤더 설정 로직 직후에 Link 헤더를 추가하여 리소스 발견 가능성(Discoverability) 확보
- 기존 edit-media 관계 유형의 시맨틱 중복을 방지하기 위해 api.w.org/action-post-process라는 전용 Relation Type 채택
- 서버 Fatal Error 발생 시에도 Attachment ID는 우선 전송하고, 정상 응답 시에만 Link 헤더를 추가하는 단계적 응답 전략 유지
- 단일 파일 내 13라인의 최소 변경을 통한 리뷰어의 인지 부하 감소 및 병합 속도 최적화
실천 포인트
- REST API 설계 시 클라이언트가 엔드포인트를 추측하지 않도록 Hypermedia as the Engine of Application State(HATEOAS) 원칙에 기반한 Link 헤더 제공 여부 검토 - API Relation Type 정의 시 기존 엔드포인트와의 시맨틱 충돌 가능성을 분석하여 고유한 네이밍 컨벤션 적용 - 오픈소스 기여 시 코드 수정 전 티켓 히스토리의 모든 코멘트를 분석하여 '재현 불가능' 또는 '설계 합의 미비' 상태의 티켓 제외 - PR 제출 전 변경 사항에 대한 논리적 근거와 설계 결정 이유를 문서화하여 리뷰어의 검토 비용 최소화