API 통신 과정은 어떻게 되나요?

API 통신 과정: 요청과 응답의 3단계 원리

API 통신 과정을 올바르게 이해하면 현대 소프트웨어가 서로 데이터를 주고받는 기본 원리를 파악하게 됩니다. 각 시스템 간의 연결 방식을 학습하여 불필요한 통신 오류를 방지하고 서비스의 효율성을 높이는 것이 중요합니다. 올바른 인터페이스 활용법을 통해 디지털 서비스의 구조를 명확히 확인하시기 바랍니다.

API 통신 과정: 웨이터가 주방에 주문을 넣는 방식

API 통신 과정은 클라이언트가 서버에 데이터를 요청(Request)하고, 서버가 이를 처리하여 응답(Response)을 반환하는 3단계로 이루어집니다. 주로 HTTP 프로토콜과 JSON 형식을 사용해 데이터를 주고받습니다.

통신 속도는 서비스 품질과 직결되는 핵심 요소입니다. 최적화된 시스템에서는 이 모든 과정이 보통 100-200 밀리초(ms) 안에 완료되어야 합니다. 응답 시간이 1초를 초과할 경우 전체 사용자의 약 32%가 즉시 이탈하기 시작합니다. 빠른^[1] 응답을 위해 데이터베이스 최적화와 효율적인 네트워크 설계가 필수적인 이유입니다.

많은 초보 개발자들이 API를 뭔가 복잡하고 마법 같은 기술로 생각합니다. 솔직히 저도 처음엔 그랬습니다. 하지만 그 원리를 하나씩 까보고 나면 결국 정해진 규칙에 따라 메시지를 주고받는 단순한 반복 작업일 뿐입니다. 전혀 겁먹을 필요가 없습니다.

클라이언트와 서버: 누가 요청하고 누가 응답하는가?

가장 헷갈리는 부분부터 명확히 정리해 보겠습니다. 통신의 양 끝단에는 항상 클라이언트와 서버가 존재합니다. 클라이언트는 웹 브라우저나 스마트폰 애플리케이션처럼 사용자가 직접 화면을 보고 조작하는 영역을 말합니다. 반면 서버는 보이지 않는 곳에서 데이터를 안전하게 보관하고 요청에 맞게 처리하는 거대한 컴퓨터입니다.

클라이언트가 묻고 서버가 대답합니다. 단순하죠.

이 둘 사이를 이어주는 다리가 바로 API(Application Programming Interface)입니다. 식당에 비유하자면 손님(클라이언트)이 요리사(서버)에게 직접 가서 음식을 만들어 달라고 하지 않습니다. 대신 웨이터(API)에게 메뉴판을 보고 주문을 맡깁니다. 웨이터는 주문을 주방에 전달하고 완성된 요리를 다시 손님 테이블로 가져옵니다.

HTTP 메서드 종류: GET과 POST는 언제 쓸까?

주방에 주문을 넣을 때도 일정한 규칙이 필요합니다. 우리는 이것을 HTTP 메서드라고 부릅니다. 각 메서드는 서버에게 데이터로 무엇을 할 것인지 명확한 의도를 전달합니다.

데이터를 단순히 읽어올 때는 GET을 사용하고, 새로운 데이터를 생성할 때는 POST를 씁니다. 정보를 수정할 때는 PUT이나 PATCH를 호출하며, 불필요한 데이터를 지울 때는 DELETE를 사용합니다. 이렇게 용도를 명확히 구분하는 것을 REST API 통신 방식이라고 합니다.

여기서 초보자들이 아주 흔하게 하는 실수가 있습니다. 바로 민감한 개인정보를 GET으로 서버에 보내는 것입니다. 절대 안 됩니다.

GET 메서드는 모든 데이터를 URL 주소 끝에 매달아서 전송합니다. 누구나 브라우저 방문 기록만 보면 전송된 데이터를 훤히 들여다볼 수 있다는 뜻입니다. 보안이 필요한 데이터는 반드시 POST를 사용해 요청 바디(Body)라는 봉투 안에 안전하게 숨겨서 보내야 합니다.

안전한 통신을 위한 필수 관문: 인증 토큰 보안

식당에서도 아무나 주방 내부로 들어갈 수 없듯, 서버 역시 아무 요청이나 덥석 받아 처리하지 않습니다. 특히 회원 정보나 결제 내역을 다루는 엔드포인트라면 더욱 엄격합니다. 이때 문지기 역할을 하는 것이 바로 인증 토큰입니다.

API 요청 오류의 상당수는 잘못된 인증 토큰 사용이나 권한 부족에서 발생합니다.^[2] 클라이언트는 먼저 로그인을 통해 서버로부터 유효한 토큰을 발급받아야 합니다. 이후 모든 API 요청의 헤더(Header) 부분에 이 토큰을 포함시켜 자신이 누구인지 증명해야만 정상적인 응답을 받을 수 있습니다.

저도 과거에 토큰의 만료 시간을 설정하지 않는 끔찍한 실수를 한 적이 있습니다. 해커가 토큰을 탈취하면 영구적으로 시스템에 접근할 수 있는 치명적인 상태였죠. - 정말 아찔했습니다 - 결국 모든 시스템의 토큰을 일괄 초기화하고 유효기간을 2시간으로 짧게 줄이는 대대적인 수정 작업을 거친 후에야 간신히 안심할 수 있었습니다. 보안은 절대 타협해선 안 되는 영역입니다.

JSON: 데이터가 이동하는 실제 모습

데이터가 네트워크를 타고 오갈 때는 서로가 완벽히 이해할 수 있는 공통 언어가 필요합니다. 과거에는 XML이라는 복잡한 형식을 주로 사용했지만, 현대의 웹과 앱 환경에서는 JSON(JavaScript Object Notation) 형식이 사실상 표준으로 자리 잡았습니다.

매우 가볍고 빠릅니다. 게다가 사람의 눈으로 읽기에도 직관적입니다.

JSON은 이름표와 그에 해당하는 값의 쌍으로 이루어집니다. 예를 들어 사용자 이름을 전달할 때 이름: 홍길동, 나이: 25 와 같이 구조화된 텍스트 형태로 묶어서 보냅니다. 불필요한 태그나 장식이 없어 네트워크 대역폭을 크게 아낄 수 있다는 장점이 있습니다.

API 호출 실패 시: 상태 코드의 진정한 의미

API 요청과 응답 과정이 늘 성공하는 것은 아닙니다. 네트워크가 끊기거나 데이터를 찾을 수 없는 등 다양한 변수가 존재합니다. 이때 서버는 처리의 성공 여부와 실패 원인을 세 자리 숫자로 요약해서 알려주는데, 이를 HTTP 상태 코드라고 부릅니다.

200번대 코드는 요청이 완벽하게 성공했음을 의미합니다. 반면 400번대 코드는 클라이언트의 잘못을 뜻합니다. 우리가 웹서핑을 하다 흔히 마주치는 404 Not Found 에러가 대표적입니다. 없는 주소를 요청했거나 삭제된 데이터를 찾으려 할 때 서버가 뱉어내는 거절 메시지입니다.

가장 두려운 것은 500번대 에러입니다. 이는 전적으로 서버 쪽 시스템에 장애가 발생했다는 뜻입니다.

처음 백엔드 개발을 시작했을 때 500 에러를 마주하고 제 코드 어딘가에 큰 버그가 있는 줄 알고 5시간 넘게 코드를 뒤적였습니다. 하지만 나중에 알고 보니 그저 데이터베이스 서버의 메모리가 가득 차서 연결이 끊어진 것이 원인이었죠. 상태 코드의 의미만 정확히 알았어도 인프라 팀에 바로 연락해 10분 만에 끝낼 수 있는 문제였습니다.

통신 성능을 극대화하는 캐싱 전략

모든 API 요청을 매번 데이터베이스까지 끌고 가서 처리하는 것은 굉장히 비효율적입니다. 실시간으로 변하지 않는 상품 목록이나 공지사항 같은 데이터는 임시 저장소에 모아두고 빠르게 꺼내 주는 편이 훨씬 유리합니다.

캐시를 적절히 활용하면 데이터베이스 조회 부하를 상당 부분 줄일 수 있습니다.^[3] 보통 Redis와 같은 인메모리 저장소를 활용해 자주 찾는 API 응답 결과를 서버 메모리에 올려둡니다. 클라이언트가 같은 요청을 보내면 데이터베이스를 거치지 않고 캐시에서 즉시 응답하므로 처리 속도가 비약적으로 상승합니다.

주요 HTTP 메서드 비교: 어떤 상황에 무엇을 써야 할까?

GET (조회)

• 브라우저나 서버 레벨에서 결과를 캐싱(저장)하여 성능을 높이기 가장 좋습니다
• 데이터가 주소창에 그대로 노출되므로 비밀번호 등 민감한 정보 전송에 절대 사용해선 안 됩니다
• URL 끝에 쿼리 스트링(Query String) 형태로 파라미터를 붙여 전송합니다
• 서버에 존재하는 데이터를 단순히 읽어오기 위해 사용합니다

⭐ POST (생성)

• 기본적으로 캐싱되지 않으며, 매 요청마다 서버가 새로운 작업을 수행해야 합니다
• GET보다 상대적으로 안전하며, HTTPS와 결합 시 데이터가 완전히 암호화됩니다
• HTTP 요청 바디(Body) 내부에 데이터를 안전하게 숨겨서 전송합니다
• 서버에 새로운 데이터를 생성하거나 민감한 정보를 제출할 때 사용합니다

PUT (수정)

• 동일한 요청을 여러 번 보내도 결과가 달라지지 않는 멱등성을 보장합니다
• 요청 바디를 사용하므로 POST와 유사한 수준의 보안을 제공합니다
• POST와 마찬가지로 요청 바디(Body)를 통해 변경할 전체 데이터를 전송합니다
• 기존에 존재하던 데이터의 전체 내용을 새로운 내용으로 교체(수정)할 때 사용합니다

주니어 개발자 민수의 아찔한 로그인 연동 실패기

서울의 한 이커머스 스타트업에 갓 입사한 주니어 개발자 민수는 앱의 첫 화면인 사용자 로그인 API 연동 업무를 맡았습니다. 처음 연동을 시도할 때 그는 모든 데이터를 조회하는 것과 동일하게 GET 메서드를 사용하여 코드를 작성했습니다.

문제는 곧바로 터졌습니다. 테스트를 진행하자 사용자의 이메일과 비밀번호가 웹 브라우저의 URL 주소창에 그대로 노출되는 심각한 결함이 발생한 것입니다. 민수는 크게 당황하여 부랴부랴 복잡한 암호화 라이브러리를 찾아 코드에 덧붙이기 시작했습니다.

며칠을 고생하던 중, 사수와의 코드 리뷰 시간에 진짜 원인을 깨닫게 되었습니다. 비밀번호와 같이 보안이 필수적인 민감한 데이터는 애초에 GET이 아닌 POST 메서드를 사용해 요청 바디 안에 넣어 보내야 한다는 가장 기초적인 원칙을 간과했던 것입니다.

결국 로그인 요청 방식을 POST로 전면 수정하고 HTTPS 프로토콜 설정을 마친 후에야 보안 문제가 말끔히 해결되었습니다. 이 사건 이후 민수는 API를 설계할 때 데이터의 성격에 따라 올바른 메서드를 선택하는 것이 개발의 첫 단추임을 뼈저리게 배웠습니다.