페이로드

프로그램끼리 값을 주고받는 가장 간단한 방법은 주소 뒤에 붙여 보내는 것입니다. 주소 끝에 물음표를 찍고 항목을 나열하면 받는 쪽이 읽습니다. 값이 두세 개일 때는 편한 방식입니다.

문제는 보낼 것이 커지거나 구조를 가질 때 생깁니다. 페이지덱 초기에 문서 저장을 이 방식으로 만들었고 짧은 메모에서는 잘 돌았습니다. 그런데 A4 두 장을 넘기는 문서에서 저장이 조용히 실패했습니다. 주소에는 길이 상한이 있어 중간에서 잘려 나갔던 것입니다.

두 번째 문제는 더 늦게 드러났습니다. 태오가 서버 접속 기록을 열었을 때 고객 문서의 본문이 기록에 그대로 남아 있었습니다. 주소는 오가는 길 곳곳에 기록으로 남는 값이라, 거기 실은 것은 숨긴 적이 없는 셈입니다.

세 번째는 구조입니다. 문서 하나에 태그가 셋 붙고 태그마다 색이 있다는 관계를 주소 한 줄로 적기는 어렵습니다. 이 셋을 풀려고 요청에 본문 칸을 따로 둔 것이 이 개념입니다.

한 번의 요청은 머리와 본문으로 나뉩니다. 머리에는 누가 보내는지, 어떤 형식으로 보내는지처럼 전달에 필요한 정보가 들어가고, 본문에는 전달하려는 내용 자체가 들어갑니다. 페이로드는 이 본문 칸을 가리킵니다.

정해야 할 것이 넷입니다.

1. 형식. 내용을 어떤 규칙으로 적을지 정합니다. 가장 널리 쓰이는 것은 데이터를 텍스트로 적는 JSON입니다. 문서를 새로 만드는 요청이라면 제목과 폴더 번호를 항목 이름과 값의 짝으로 적어 보냅니다. 사람이 그대로 읽을 수 있는 형식이라 무엇이 잘못됐는지 눈으로 확인하기 쉽습니다.
2. 형식을 알리는 일. 어떤 형식으로 보냈는지는 머리에 따로 적어 줍니다. 받는 쪽은 그 표시를 보고 해석 방법을 고르므로, 표시와 실제 내용이 어긋나면 내용이 멀쩡해도 요청이 거절됩니다. 연동 첫날에 가장 자주 나오는 오류가 여기서 나옵니다.
3. 어떤 요청에 붙는지. 요청의 성격은 HTTP 메서드라는 동사로 구분되고, 본문이 붙는 요청과 안 붙는 요청이 갈립니다. 읽기만 하는 요청에는 보통 본문을 싣지 않고 필요한 조건을 주소에 적습니다. 새로 만들거나 고치는 요청에는 본문이 붙습니다.
4. 응답 쪽. 본문은 돌아오는 길에도 실립니다. 결과가 어땠는지는 상태 코드라는 세 자리 숫자가 알려 주고, 그 숫자와 함께 본문이 옵니다. 문서가 잘 만들어졌으면 만들어졌다는 뜻의 숫자와 함께 방금 생긴 문서의 번호가 본문에 담겨 오고, 부르는 쪽은 그 번호를 들고 다음 요청을 보냅니다.

크기에는 상한이 걸려 있습니다. 서버나 중간 장비가 1메가바이트 같은 선을 정해 두고 넘으면 거절합니다. 그래서 이미지나 첨부 파일은 본문에 그대로 담지 않고 파일을 따로 올린 뒤 그 주소만 본문에 적습니다. 상한을 모른 채 만들면 시연에서는 잘 돌고 실제 고객 데이터에서 실패하는 기능이 나옵니다.

가장 먼저 쓰이는 자리는 연동 규격을 적는 문서입니다. 어떤 항목이 필수이고 어떤 항목이 선택인지, 값의 형태가 숫자인지 글자인지가 여기서 정해집니다. 이 규격이 비면 연동하는 쪽은 요청을 보내 보고 거절당하는 방식으로 알아 가게 됩니다.

두 번째는 문제를 찾는 자리입니다. 연동이 실패했을 때 태오가 가장 먼저 보는 것이 주고받은 본문입니다. 보낸 쪽이 무엇을 담았고 받은 쪽이 무엇을 돌려줬는지를 나란히 놓으면 대개 그 자리에서 원인이 보입니다. 기록에 남길 때 걸러야 할 것이 있습니다. 비밀번호와 인증 토큰 같은 값은 본문에 담겨 오더라도 기록에는 가려서 남깁니다. 문제를 찾으려 남긴 기록이 새 나가면 그 기록이 사고가 됩니다.

세 번째는 사건이 생긴 쪽이 먼저 알려 주는 웹훅입니다. 결제가 승인되면 결제사가 우리 주소로 요청을 보내는데, 무슨 일이 일어났는지가 그 본문에 담겨 옵니다. 받는 쪽에서는 이 본문이 정말 그 회사에서 온 것인지 확인해야 합니다. 주소만 알면 누구나 같은 모양의 본문을 보낼 수 있기 때문입니다.

네 번째는 보안입니다. 본문에 담겨 들어온 값을 그대로 믿으면 사고가 됩니다. 요금제를 바꾸는 요청의 본문에 플랜 이름과 금액이 함께 담겨 있고 서버가 그 금액을 그대로 받아 적으면, 금액만 0으로 고쳐 보낸 요청이 통과합니다. 값은 받는 쪽에서 다시 확인합니다.

다섯 번째는 규격을 바꿀 때입니다. 항목 하나를 빼거나 이름을 바꾸면 이미 연동해 둔 쪽이 멈추므로, 새 항목을 더하고 옛 항목을 한동안 같이 내보냅니다. 이 구분을 놓치면 브레이킹 체인지가 됩니다.

"페이로드 좀 찍어서 보내 주세요. 뭘 보내고 있는지부터 봐야 합니다."

요청 본문의 실제 내용을 확인하자는 요청입니다.

"형식 표시가 안 맞아서 400 떨어지는 거예요."

본문은 멀쩡한데 머리에 적힌 형식이 어긋났다는 진단입니다.

"파일은 페이로드에 넣지 말고 따로 올린 다음 주소만 주세요."

크기 상한에 걸리지 않게 구조를 바꾸자는 말입니다.

페이지덱에서는 태오가 연동 규격을 정할 때 본문의 항목 목록을 먼저 적습니다. 화면을 그리기 전에 이 목록을 지현과 맞춰 두는데, 화면에 보이는 값과 서버가 받는 항목이 어긋나면 나중에 양쪽을 다 고쳐야 하기 때문입니다.

페이로드가 곧 JSON이라고 여기는 경우가 많습니다. 실무에서 만나는 본문의 대부분이 그 형식이라 자연스러운 오해입니다. 하지만 본문에 담기는 것은 형식과 무관한 자리입니다. 파일을 올릴 때는 파일 내용이 그대로 실리고, 서비스끼리 빠르게 주고받는 구간에서는 사람이 읽을 수 없는 형식이 실립니다. 본문과 형식을 한 덩어리로 이해하면 형식이 다른 연동을 만났을 때 어디를 봐야 할지 모릅니다.

한 번에 많이 담는 것이 낫다고 보는 것도 흔합니다. 요청 수가 줄어드니 빠를 것처럼 보입니다. 그런데 본문이 커지면 세 가지가 함께 커집니다. 상한에 걸릴 위험, 받는 쪽이 처리하는 시간, 그리고 실패했을 때 잃는 것입니다. 문서 500건을 한 요청에 담아 보내면 마지막 한 건이 잘못돼도 전체가 거절될 수 있고, 그러면 무엇까지 처리됐는지 알 수 없는 상태가 됩니다. 100건씩 다섯 번 보내는 쪽이 느려 보여도 되돌리기 쉽습니다.