API

프로그램끼리 무언가를 주고받으려면 상대의 안쪽을 직접 들여다보는 수밖에 없던 시절이 있었습니다. 회원 목록이 필요하면 상대 시스템의 저장소 계정을 받아 표를 직접 읽었고, 그것도 안 되면 밤마다 파일 하나를 만들어 서버에 올려 두고 상대가 받아 가게 했습니다.

이 방식의 문제는 한쪽이 자기 안쪽을 고치는 순간 드러났습니다. 회원 표에서 칸 이름을 name 에서 user_name 으로 바꾸면, 그 표를 읽어 가던 다른 팀과 다른 회사의 화면이 같은 날 아침에 동시에 멈췄습니다. 고친 쪽은 자기가 무엇을 깨뜨렸는지 몰랐고, 깨진 쪽은 왜 깨졌는지 몰랐습니다. 남의 안쪽에 기대어 붙어 있었으니 안쪽이 흔들리면 같이 흔들릴 수밖에 없었습니다.

페이지덱에서도 초기에 같은 일이 있었습니다. 태오가 결제 기록 표에 칸을 하나 더하려다 말고 손을 멈췄습니다. 그 표를 누가 어디서 읽고 있는지 아무도 정확히 몰랐기 때문입니다. 물어볼 사람을 찾는 데 이틀이 걸렸고, 결국 칸을 더하는 대신 새 표를 하나 만들어 같은 데이터를 두 곳에 쌓는 쪽을 골랐습니다. 안쪽이 밖으로 새어 나가 있으면 고치는 값이 이렇게 뜁니다.

API 는 창구를 하나 세워서 이 문제를 끊습니다. 안쪽이 어떻게 생겼는지는 감추고, 밖에서 부를 수 있는 창구의 목록과 창구마다 받는 값·돌려주는 값만 공개합니다. 창구 뒤에서 표를 어떻게 바꾸든 창구가 그대로면 부르는 쪽은 아무것도 고치지 않습니다. 약속이 문서로 남아 있으면 화면 쪽과 서버 쪽이 서로를 기다리지 않고 동시에 일할 수 있고, 다른 회사 서비스를 끌어다 쓰는 일도 이 창구를 통합니다.

API 아래 묶인 말은 여섯 갈래입니다. 어떤 방식으로 주고받느냐가 방식이고, 오가는 것의 모양을 무엇으로 정해 두느냐가 규격입니다. 열어 둔 창구를 어떻게 굴리느냐가 운영, 약속을 어디에 적어 두느냐가 문서입니다. 나머지 둘은 약속을 깨뜨리는 변경(위험)과 깨뜨리지 않으려고 지키는 성질(원칙)입니다.

방식은 주고받는 모양새를 가르는 갈래이고 다섯 가지가 있습니다. 나뉘는 기준은 누가 먼저 말을 거느냐와 한 번에 얼마나 정확히 필요한 것만 받느냐입니다.

1. REST — 데이터 하나하나에 주소를 붙여 두고 그 주소를 불러서 읽고 쓰는 방식입니다. 웹에서 가장 널리 쓰여서 대개 여기서 시작합니다.
2. GraphQL — 부르는 쪽이 필요한 항목만 골라 적어 보내고 딱 그만큼만 받아 옵니다. 화면 하나를 그리려고 창구를 다섯 번 부르던 일이 한 번으로 줄어드는 대신, 창구를 여는 쪽이 준비할 것이 늘어납니다.
3. gRPC — 회사 안의 서비스끼리 빠르게 주고받을 때 쓰는 규격입니다. 사람이 읽기 좋은 형식 대신 기계가 읽기 좋은 형식을 써서 속도를 얻습니다.
4. 웹훅 — 방향이 반대입니다. 부르는 쪽이 계속 물어보는 대신, 사건이 생긴 쪽이 상대 주소로 먼저 알려 줍니다. 결제가 승인되는 순간을 알고 싶을 때 1분마다 물어보지 않아도 됩니다.
5. 웹소켓 — 연결을 열어 둔 채로 양쪽이 아무 때나 말을 겁니다. 같은 문서를 둘이 동시에 편집할 때처럼 한쪽의 변화가 즉시 반대쪽에 보여야 하는 자리에 씁니다.

규격은 오가는 것의 모양을 정해 두는 갈래입니다. 창구를 열어 놓기만 해서는 대화가 안 되고, 무엇을 요청인지 알아보고 결과를 어떻게 읽을지까지 맞춰 두어야 합니다. 요청의 성격은 HTTP 메서드라는 동사로 구분합니다. 읽기만 하는 요청과 새로 만드는 요청과 지우는 요청이 각각 다른 동사를 달고 오기 때문에, 받는 쪽은 본문을 열어 보기 전에 무슨 일이 벌어질지 압니다. 결과는 상태 코드라는 세 자리 숫자로 돌아옵니다. 200 은 잘됐다는 뜻이고 404 는 찾는 것이 없다는 뜻이며 500 은 받는 쪽이 고장 났다는 뜻이라서, 부르는 쪽은 숫자만 보고 다시 시도할지 사람을 부를지 정합니다. 요청과 응답에 실려 오가는 본문은 페이로드라고 부르고, 그 본문을 적는 형식으로는 JSON이 널리 쓰입니다. 사람이 그대로 읽을 수 있는 텍스트라서 무엇이 잘못됐는지 눈으로 확인하기 쉽습니다. 이 셋이 한 번의 왕복에 같이 실립니다. 문서 하나를 새로 만들 때는 만들기를 뜻하는 동사에 제목과 내용을 담은 본문을 붙여 보내고, 잘 만들어졌으면 201 이라는 숫자와 함께 방금 만들어진 문서의 번호가 담긴 본문이 돌아옵니다. 부르는 쪽은 그 번호를 들고 다음 요청을 보냅니다.

운영은 열어 둔 창구를 굴리는 갈래입니다. 창구는 만들고 끝나지 않고, 열려 있는 동안 계속 누군가가 두드립니다. API 게이트웨이는 서비스가 여럿일 때 입구를 하나로 모아 주는 층입니다. 누구인지 확인하고 기록을 남기는 일을 서비스마다 따로 짜는 대신 입구에서 한 번에 처리합니다. 요청 제한은 한 사람이 정해진 시간에 보낼 수 있는 요청 수를 묶어 둡니다. 연동한 쪽에서 실수로 1초에 수천 번을 부르면 창구 뒤의 서비스가 같이 멈추기 때문에, 분당 60회 같은 선을 긋고 넘으면 잠시 거절합니다. API 버저닝은 규격이 바뀔 때 옛 판과 새 판을 나란히 두는 일입니다. 쓰던 쪽이 옮겨 갈 시간을 벌어 주는 장치입니다.

문서는 약속을 적어 두는 갈래입니다. OpenAPI는 창구 목록과 각 창구가 받는 값·돌려주는 값을 기계가 읽을 수 있는 형식으로 적는 표준입니다. 사람이 읽는 설명서와 다른 점은 그 파일 하나에서 문서 화면과 연동용 코드와 검사 도구가 자동으로 나온다는 데 있습니다. 문서와 실제 동작이 어긋나는 흔한 사고가 여기서 줄어듭니다.

마지막 둘은 짝입니다. 브레이킹 체인지는 쓰던 쪽의 코드를 깨뜨리는 변경입니다. 응답에서 칸을 없애거나 이름을 바꾸거나 필수 입력을 새로 요구하면 어제까지 돌던 연동이 오늘 멈춥니다. 하위 호환성은 그 반대 방향의 성질로, 새 것을 더하되 옛 방식도 계속 받아 주는 상태를 가리킵니다. 칸을 없애는 대신 새 칸을 더하고, 옛 칸은 한동안 같이 내보내는 식입니다.

여섯 갈래는 한 줄로 이어집니다. 방식을 고르면 규격이 따라오고, 규격이 정해지면 문서로 적히고, 적힌 문서를 보고 남이 붙기 시작하면 그때부터 운영과 위험이 생깁니다. 아무도 쓰지 않는 창구에는 브레이킹 체인지라는 말이 필요 없습니다.

"그쪽 API 나와 있어요? 있으면 이번 주에 붙일 수 있어요."

상대가 창구를 공개해 뒀는지 묻는 말입니다. 있으면 붙이는 일이고 없으면 상대가 먼저 만들어야 하는 일이라, 일정이 주 단위에서 분기 단위로 바뀝니다.

"그건 API 스펙이 바뀌는 거라 쓰던 쪽이 다 깨져요. 판을 나눠서 가시죠."

지금 하려는 수정이 밖에 이미 나간 약속을 건드린다는 지적입니다. 옛 판을 남긴 채 새 판을 따로 내자는 제안이 뒤에 붙습니다.

"API 문서부터 맞추고 화면이랑 서버 동시에 시작하죠."

주고받을 값을 먼저 확정하면 양쪽이 서로를 기다리지 않아도 된다는 말입니다.

페이지덱에서 이 말이 가장 자주 오간 때는 기업 고객 한 곳이 자기네 사내 시스템에서 페이지덱 문서 목록을 읽어 가고 싶다고 요청했을 때입니다. 수아가 요청을 들고 왔고, 지현이 범위를 문서 목록 읽기 하나로 좁혔습니다. 태오는 이미 화면이 쓰고 있던 내부 창구를 그대로 열자고 했다가 접었습니다. 내부 창구에는 다른 화면에서만 쓰는 값이 섞여 있어서, 한번 밖에 나가면 그 값들까지 약속이 되어 버리기 때문입니다.

그래서 밖으로 낼 창구를 따로 만들고 무엇을 돌려줄지 먼저 문서로 적었습니다. 문서가 나온 날 고객사 개발자는 아직 아무것도 만들어지지 않은 상태에서 자기 쪽 코드를 짜기 시작했고, 태오는 같은 주에 서버 쪽을 채웠습니다. 열고 나서 한 달 뒤 응답에 수정한 사람 이름을 더해 달라는 요청이 왔을 때는, 기존 칸을 그대로 두고 새 칸만 더하는 방식으로 처리했습니다. 고객사 쪽은 아무것도 고치지 않았고 새 칸이 필요해진 뒤에 읽기 시작했습니다.

한 번 연 API 도 필요하면 언제든 고칠 수 있다고 생각하기 쉽습니다. 코드는 우리 저장소에 있고 배포 버튼도 우리가 누르니 자기 것처럼 보입니다. 하지만 창구를 공개한 순간 그 모양은 밖에 나가 있는 남의 코드가 딛고 선 바닥이 됩니다. 응답에서 칸 하나를 지우는 일은 우리 쪽에서는 한 줄이지만, 그 칸을 읽던 고객사 세 곳에서는 배포 없이 화면이 멈추는 사고입니다. 그래서 공개된 창구의 변경은 기능 수정이 아니라 약속 변경으로 다루고, 없애는 대신 더하고 꼭 없애야 하면 미리 알린 뒤 판을 나눕니다.

API 가 있으니 연동은 금방 된다는 기대도 자주 봅니다. 창구 주소와 문서를 받으면 절반은 끝난 것처럼 보이니 그렇게 읽힙니다. 실제로 시간을 쓰는 곳은 그다음입니다. 누구인지 증명하는 열쇠를 발급받아 안전하게 보관해야 하고, 분당 몇 번까지 부를 수 있는지에 맞춰 호출을 나눠야 하고, 상대가 잠시 고장 났을 때 다시 시도할지 멈출지를 정해야 합니다. 양쪽이 같은 것을 다른 이름과 다른 단위로 부르는 일도 흔해서 그 대응표를 만드는 데만 며칠이 갑니다. 이 부분을 일정에서 빼고 잡으면 이틀짜리로 약속한 연동이 2주가 되고, 그 차이가 고객에게 한 약속을 어기는 첫 번째 이유가 됩니다.