4장 프로그램과 API를 연결하는 약속

사람이 읽는 소스 코드가 그대로 모든 컴퓨터에서 실행되는 것은 아니다. 언어와 실행 방식에 따라 기계어로 변환하거나 중간 표현을 거치거나 실행 환경이 명령을 해석한다. 실제 시스템은 이 방식을 섞기도 한다. 중요한 질문은 “컴파일 언어인가?” 하나가 아니라 어떤 파일이 만들어지고, 그것을 실행하려면 무엇이 필요한가다.

개발자의 노트북에서는 되는데 서버에서는 안 되는 문제를 생각해 보자. 코드가 같아도 라이브러리 버전, 운영체제, CPU 구조, 시간대, 설정이 다를 수 있다. 프로그램의 동작을 설명하는 최소 단위는 소스 파일 한 장보다 크다. 실행에 필요한 의존성과 설정을 함께 관리해야 다른 환경에서도 같은 결과에 가까워진다.

함수 호출이 네트워크를 건널 때

API는 서로 다른 구성 요소가 상호작용하는 방법을 정한 인터페이스다. 꼭 웹 주소만 뜻하는 것은 아니다. 운영체제 기능을 부르는 인터페이스도 API다. 이 책에서는 주로 네트워크로 요청과 응답을 주고받는 웹 API를 다룬다. 입력 형식, 인증 방법, 성공 결과, 오류, 시간 제한이 약속의 일부다.

같은 프로그램 안에서 함수를 부르는 것과 멀리 있는 서버에 요청하는 것은 다르다. 네트워크 호출은 지연되거나 끊기거나 응답만 사라질 수 있다. 요청을 보낸 쪽에서 시간 초과를 봤다고 해서 상대편이 작업을 수행하지 않았다는 뜻은 아니다. 특히 결제나 주문처럼 상태를 바꾸는 호출에서는 이 모호함을 설계에 포함해야 한다.

가상의 도서 대여 API가 있다고 하자. 사용자가 대여 버튼을 누르면 서버는 재고를 확인하고 대여 기록을 남긴다. 기록은 저장됐지만 응답이 도중에 사라지면 사용자는 다시 누를 수 있다. 서버가 매 요청을 새로운 대여로 처리한다면 중복 기록이 생긴다. 요청 식별자나 업무 규칙을 통해 같은 의도를 다시 처리해도 결과가 중복되지 않게 만드는 장치가 필요하다.

다음은 실제 서비스 주소가 아닌 설계용 예다. JSON에서 숫자와 문자열은 다른 형식이다. 식별자를 숫자로 표현하면 선행 0이 사라지거나 다른 언어에서 정밀도 문제가 생길 수 있으므로, 계산하지 않는 식별자는 문자열이 적절한 경우가 많다. 시간은 기준 시간대까지 함께 전달해야 해석이 덜 흔들린다.

{
  "request_id": "loan-demo-0007",
  "member_id": "00042",
  "book_id": "NET-101",
  "requested_at": "2026-09-05T03:00:00Z",
  "result": {
    "status": "accepted",
    "loan_id": "LN-2026-00418"
  }
}

오류도 인터페이스다

성공 화면만 정의한 API는 운영에서 쉽게 흔들린다. 권한이 없는 경우, 입력이 잘못된 경우, 자원이 없는 경우, 서버가 잠시 과부하인 경우를 구분해야 한다. 사용자에게 보여 줄 설명과 개발자가 원인을 추적할 식별자는 목적이 다르다. 내부 경로나 데이터베이스 오류 전체를 외부 응답으로 내보낼 필요는 없다.

오류가 발생했을 때 재시도가 가능한지도 약속해야 한다. 입력 형식이 잘못된 요청을 그대로 다시 보내는 것은 도움이 되지 않는다. 일시적인 장애는 잠시 기다렸다 재시도할 수 있지만, 끝없이 즉시 반복하면 상대 서버의 회복을 방해한다. 재시도 횟수, 기다리는 간격, 전체 마감 시간을 함께 설계해야 한다. 네트워크는 오류를 없애 주는 선이 아니라 오류를 다루어야 하는 경계다.

API의 필드를 바꿀 때는 현재 코드를 사용하는 다른 프로그램을 생각해야 한다. 새 필드를 추가하는 변화와 기존 필드의 의미를 바꾸는 변화는 영향이 다르다. 알 수 없는 필드를 무시하도록 설계한 소비자도 있고 모든 필드를 엄격히 검사하는 소비자도 있다. “추가만 했으니 안전하다”는 추측 대신 실제 계약과 호환성 검사를 확인하자.

문서에는 성공 예시 하나보다 잘못된 입력의 처리, 크기 제한, 정렬 기준, 페이지 이동 방식, 시간대, 중복 요청 정책이 더 중요한 경우가 많다. 사람이 운영 중에 물어볼 질문이 곧 문서에 필요한 항목이다. 완벽한 설명서를 먼저 쓰라는 뜻은 아니다. 다른 사람이 호출할 수 있을 만큼 경계를 명시하고, 바뀌는 약속을 추적하라는 뜻이다.

프로그램은 코드만으로 존재하지 않는다. 실행 환경, 데이터, 인터페이스, 운영 절차와 함께 살아간다. 앞으로 네트워크를 공부할 때도 이 사실을 기억하자. 패킷이 도착했다는 것과 사용자의 일이 끝났다는 것은 다르다. 연결의 성공을 업무의 성공까지 이어 주는 책임은 결국 프로그램과 그 프로그램을 설계한 사람에게 있다.