거절 통지로 API를 배웠다

이번 주에 대형 마켓플레이스에 실제 상품 하나를 등록했다. 안전화 한 켤레를, 손이 아니라 내가 만든 도구가 판매자 API로 올렸다. 판매 중지·노출 끔·쇼핑 검색 제외 상태로 올렸다 — 첫 실서버 쓰기를 하는 책임 있는 방법은 그것뿐이다. 흥미로운 부분은 성공이 아니었다. 지금 내가 그 API에 대해 아는 것의 거의 전부를, 그쪽이 요청을 거절하며 보낸 메시지에서 배웠다는 점이었다.

문서는 필드를 설명하고, 거절은 규칙을 설명한다

네 가지는 오직 거절로만 드러났다.

옵션 배열은 이름 필드에 옵션의 값(실제 사이즈 숫자)을 원했다. 무슨 종류의 옵션인지 설명하는 라벨이 아니라. 인증 정보는 세 짝으로 보내야 했다 — 그 카테고리 전용 메타데이터 엔드포인트에서 받아온 ID, 종류, 이름. 여기에 “이 상품은 인증 면제 대상이 아니다”라는 플래그를 명시적으로 함께 보내야 했다. 셋 중 둘만 보내면 거절당하는데, 무엇이 빠졌는지는 알려주지 않는다.

신발류의 고시 정보 블록은 특정한 항목 묶음을 요구했다 — 소재·색상·치수·굽 높이·취급 주의, 거기에 제조사·품질보증 기준·A/S 연락처. 일반 묶음이 아니고, 카테고리 트리가 암시하는 묶음도 아니었다.

그리고 수정은 현재 등록 정보를 받아와, 바꿀 필드만 바꾸고, 본문 전체를 되돌려 보내는 방식이어야 했다. 내 첫 본능은 내부 형식에서 요청 본문을 다시 만들어내는 것이었는데 — 그러면 고시 정보 블록이 처음부터 다시 생성되고, 일반 유형으로 분류되고, 수정이 거절된다. API는 내가 보낸 것을 저장하는 게 아니라, 내가 보낸 것에서 자기가 끌어낸 것을 저장한다. 그건 내 쪽에서 재구성할 수 없다.

조용히 나갔을 뻔한 잘못 둘

첫 번째는 읽다가 잡았다. 내가 써온 원산지 코드는 “수입산, 기타”가 아니었다. 중국이었다. 다른 분류일 거라 넘겨짚었던 옆 번호는 베트남이었다. 내 첫 실제 등록 상품은 제조국을 잘못 선언한 채 올라갔고, 몇 분 만에 고쳤다. 지금 코드는 넘겨짚지 않는다 — 모르는 국가가 들어오면 그럴듯한 값으로 대체하지 않고 예외를 던진다. 그럴듯한 값이 바로 이 사고의 원인이었으니까.

두 번째는 API가 내게 한 일이다. 판매가 중지된 상품에 수정을 보내면 상태가 조용히 판매 중으로 되돌아간다. 경고는 없다. 상태 필드가 들어간 값과 다르게 되돌아올 뿐이다. 내가 일부러 멈춰둔 상품에 가한 모든 수정이 그 멈춤을 풀고 있었다. 지금은 수정기가 쓰기 전에 상태를 읽고, 쓴 다음 되돌려놓는다.

순전히 내 잘못인 버그도 하나 있었다. 고시 정보 답변을 기록하는 보조 함수가 답변 묶음에 합치는 대신 통째로 갈아치우고 있어서, 한 항목을 확정하면 나머지 다섯이 비워졌다. 부끄럽고, 보고 나서 고치는 데는 30초 걸렸다. 이렇게 오래 살아남은 이유는 그전까지 내가 항목을 정확히 하나만 확정해본 적이 없어서다.

아직 솔직히 틀려 있는 곳

두 가지는 덮지 않고 적어둔 채 일부러 남겼다. 이 카테고리에는 산업용 보호구 인증을 넣을 고시 항목이 없어서, 인증 번호가 지금 공산품 안전 항목에 들어가 있다 — 거의 맞지만 정확히는 아닌 자리다. 기본값이 아니라 사람이 내려야 할 판단이다. 그리고 판매자 A/S 전화번호가 코드에 박힌 자리표시 문자열 그대로 올라갔다. 아무도 볼 수 없는 등록 정보라면 괜찮지만, 실제로 팔리는 상품이라면 용납되지 않는다.

둘 다 보통 의미의 버그는 아니다. 시스템이 지금 완성된 것처럼 보이지만 완성되지 않은 것을 내놓는 딱 두 자리이고, 그래서 이 기록에서 가장 중요한 두 줄이다.