기획자가 개발을 얼마나 알아야 하냐는 질문에는 대개 범위로 답이 돌아옵니다. 이만큼은 알아야 한다는 목록이요. 그런데 실제로 도움이 되는 건 넓이가 아니라 지점이었습니다. 한 곳만 정확히 알면 되는데, 그 자리가 API 문서입니다.
코딩을 배우라는 조언이 잘 안 먹히는 이유도 여기 있습니다. 문법을 익힌다고 우리 서비스가 무엇을 주고받는지 알게 되지는 않으니까요. 몇 달 배워도 회의에서 쓸 일이 없고, 그러다 보면 배운 것도 흐려집니다.
API 문서는 메뉴판에 가깝습니다. 무엇을 파는지, 주문하려면 무엇을 말해야 하는지, 그러면 무엇이 나오는지가 적혀 있습니다. 없는 메뉴는 아무리 정중하게 부탁해도 안 나온다는 것까지요.
이걸 안 보고 기획하면 이런 일이 생깁니다. 게시판에 활동 포인트와 레벨을 붙이기로 하고, 글 목록에도 작성자 레벨을 보여달라고 요청합니다. 돌아오는 답은 안 된다는 말입니다. 문서를 열어보면 이유가 있습니다. 글 목록을 가져오는 응답에 작성자 이름만 문자열로 들어 있고 사용자 아이디가 없습니다. 레벨은 별도 API로 가져와야 하는데 그러려면 아이디가 필요하고요.
여기서부터가 갈립니다. 문서를 미리 봤다면 요청 전에 이미 알았을 겁니다. 목록 응답에 아이디와 레벨을 추가하는 방법과, 목록을 받아온 뒤 작성자마다 따로 조회하는 방법. 앞엣것은 화면이 깔끔한 대신 서버를 고쳐야 하고, 뒤엣것은 고칠 게 적은 대신 호출이 늘어납니다. 아예 레벨을 목록 말고 상세 화면에만 두는 선택지도 있습니다. 문서를 안 보면 이 셋 중 무엇도 못 꺼내고 안 된다는 답만 받습니다.
문서에서 볼 곳은 많지 않습니다. 무엇이 필수값이고 무엇이 선택인지, 돌아오는 값이 내가 기획한 걸 만들기에 충분한지. 그리고 응답 코드 몇 개. 200은 잘 받았다는 뜻이고 404는 주소가 틀렸다는 뜻인데, 400번대는 우리가 잘못 보낸 거고 500번대는 저쪽 서버 문제라는 것 정도만 알아도 대화가 달라집니다.
호출 횟수도 봅니다. 목록에 스무 개가 뜨는데 각각 한 번씩 더 물어야 한다면 화면 한 번에 스물한 번을 부르는 셈이고, 그 API가 그만큼을 받아주는지가 기획 단계의 질문이 됩니다.
보고 나면 미리 해둘 일도 생깁니다. 남의 서비스를 붙이는 일이라면 API 키를 먼저 발급받아 두거나, 요청이 오갈 통로를 열어달라고 인프라 담당자에게 미리 말해둘 수 있습니다. 개발자가 착수한 다음에 이걸 시작하면 그 며칠이 그대로 일정이 됩니다.
그래서 달라지는 건 태도가 아니라 요청의 모양입니다. 되느냐고 묻는 자리에, 지금 응답에 무엇이 들어 있고 무엇이 빠져 있는지가 대신 들어갑니다.
요즘도 새 기능 이야기가 나오면 회의 자료보다 그 문서를 먼저 엽니다.