2026. 6. 9. 23:46ㆍ시즌 1 | 기초 기술 개념
DevRel 준비 4주차 | 기초 기술 개념
지난 글에서는 웹과 앱의 차이, 그리고 프론트엔드와 백엔드라는 구조를 배달 앱과 쇼핑 앱, 은행 앱을 예시로 살펴봤습니다. 마지막에 잠깐 언급했던 "프론트엔드와 백엔드가 어떻게 대화하는지"에 대한 이야기를 본격적으로 해볼 차례입니다.
오늘의 주제는 API입니다. 그리고 출발점은 우리가 매일 하는 아주 익숙한 행동입니다. 바로 로그인 버튼을 누르는 것입니다.
"아이디와 비밀번호를 입력하고 로그인 버튼을 누른다." 이 단순해 보이는 행동 뒤에는 생각보다 훨씬 많은 일이 빠르게 일어납니다. Technical Writer로 일하면서 개발자분들과 대화할 때 자주 듣던 "API 요청", "응답 처리" 같은 용어들이 실제로 무엇을 의미하는지, 오늘 그 흐름을 단계별로 따라가보겠습니다.
API란 무엇인가: 식당의 주문서 시스템
지난 주에 프론트엔드를 식당의 홀, 백엔드를 주방에 비유했습니다. 그렇다면 API는 무엇일까요? 저는 홀 직원이 주방에 전달하는 주문서라고 이해했습니다.
손님(사용자)이 홀(프론트엔드)에서 "김치찌개 하나 주세요"라고 말하면, 홀 직원은 그 내용을 주문서에 정확한 형식으로 적어서 주방(백엔드)에 전달합니다. 주방은 주문서를 받아 요리를 완성하고, 다시 홀 직원을 통해 손님에게 음식을 가져다줍니다.
여기서 중요한 것은 주문서의 형식입니다. 주방은 자신들이 이해할 수 있는 형식으로 주문서가 와야 일을 시작할 수 있습니다. "김치찌개, 1인분, 테이블 5번"처럼 약속된 형식이 있어야 하죠.
API(Application Programming Interface)란, 서로 다른 소프트웨어가 정해진 방식으로 데이터를 주고받을 수 있도록 만들어진 통신 규칙입니다.
로그인 버튼을 누르면: 단계별 흐름 따라가기
이제 실제로 로그인 버튼을 누르는 순간부터 "로그인 성공" 화면이 뜨기까지 어떤 일이 일어나는지 단계별로 따라가보겠습니다.
1단계: 사용자가 정보를 입력하고 버튼을 누른다 (프론트엔드)
화면에 있는 아이디 입력창에 missdev@email.com을 입력하고, 비밀번호창에 비밀번호를 입력한 뒤 로그인 버튼을 클릭합니다. 이 모든 것은 프론트엔드의 영역입니다. 화면을 그리고, 입력값을 받고, 버튼 클릭을 감지하는 것이죠.
2단계: 프론트엔드가 백엔드에 요청을 보낸다 (API 요청)
버튼이 눌리는 순간, 프론트엔드는 백엔드 서버를 향해 이런 내용의 **요청(Request)**을 보냅니다:
Copy"이 아이디와 비밀번호를 가진 사람이 맞는지 확인해줘."
이 요청은 인터넷을 통해 서버로 전달되며, API가 정의한 형식에 맞게 포장되어 있습니다. 아이디와 비밀번호 같은 민감한 정보는 암호화되어 전달됩니다.
3단계: 백엔드가 데이터베이스에서 확인한다 (서버 처리)
요청을 받은 백엔드 서버는 이렇게 생각합니다:
"이 이메일 주소로 가입된 계정이 있나? 있다면 비밀번호가 일치하나?"
서버는 데이터베이스(회원 정보가 저장된 거대한 창고)에 접근해서 해당 이메일 계정을 찾고, 입력된 비밀번호가 저장된 것과 일치하는지 대조합니다.
4단계: 백엔드가 결과를 응답으로 돌려보낸다 (API 응답)
확인이 끝나면 백엔드는 프론트엔드에 **응답(Response)**을 보냅니다:
- 성공: "맞습니다. 이 사용자의 이름은 MissDev이고, 이 토큰을 가지고 있으면 로그인 상태를 유지할 수 있습니다."
- 실패: "비밀번호가 틀렸습니다."
5단계: 프론트엔드가 응답을 받아 화면을 바꾼다
응답을 받은 프론트엔드는 그 내용에 맞게 화면을 업데이트합니다. 성공이라면 메인 화면으로 이동하고, 실패라면 "비밀번호를 확인해주세요"라는 메시지를 화면에 표시합니다.
이 모든 과정이 우리가 버튼을 누르고 화면이 바뀌는 그 짧은 순간에 일어납니다.
카카오 로그인 버튼에 숨어 있는 API의 세계
"카카오 계정으로 로그인" 버튼을 본 적 있으시죠? 이 버튼은 API를 이해하기에 아주 좋은 예시입니다.
어떤 쇼핑몰 앱에서 "카카오로 로그인" 버튼을 누르면, 그 쇼핑몰은 카카오가 제공하는 로그인 API를 사용합니다. 쇼핑몰 개발자가 카카오 로그인 시스템을 처음부터 직접 만든 것이 아니라, 카카오가 "우리 로그인 기능을 이렇게 연결하면 사용할 수 있어요"라고 정의해둔 API 규칙을 따라서 연결한 것입니다.
이것이 API의 또 다른 중요한 역할입니다. 이미 잘 만들어진 기능을 다른 서비스에서도 쉽게 가져다 쓸 수 있게 해주는 것이죠. 네이버 지도 API, 카카오페이 결제 API, 날씨 API처럼 다양한 기능들이 API 형태로 제공되고, 수많은 서비스들이 이를 연결해서 사용합니다.
Technical Writer 관점에서: API 문서가 막히는 순간
이 부분은 제가 직접 경험하면서 느낀 것을 솔직하게 적어보겠습니다.
기술 문서를 작성하면서 API 관련 내용을 처음 접했을 때, 가장 막혔던 부분은 **"어디서부터 어디까지가 내가 설명해야 할 영역인가"**를 파악하는 것이었습니다.
API 문서는 일반 사용자 설명서와 다릅니다. 사용자 설명서는 "이 버튼을 누르면 이런 화면이 나옵니다"라고 결과 중심으로 쓸 수 있습니다. 하지만 API 문서는 개발자가 대상이기 때문에, "이 요청을 이 형식으로 보내면, 서버는 이런 응답을 돌려줍니다"라는 요청과 응답의 구조를 정확하게 명세해야 합니다.
예를 들어:
- 나쁜 예: "요청 형식이 올바르지 않은 경우 400 에러가 발생할 수 있습니다."
- 좋은 예: "필수 파라미터인 email 또는 password가 누락되었거나, JSON 형식이 잘못된 경우 400 Bad Request를 반환합니다."
오늘 다룬 요청과 응답의 흐름을 이해하고 나서야, API 문서가 왜 그런 형식으로 쓰여 있는지가 비로소 보이기 시작했습니다. 개념을 이해하는 것이 문서를 읽는 능력을 바꾼다는 것을 그때 처음 실감했습니다.
마무리하며
오늘 다룬 내용을 짧게 정리해보겠습니다.
- API는 프론트엔드와 백엔드, 또는 서로 다른 서비스가 약속된 방식으로 데이터를 주고받는 통신 규칙입니다
- 로그인 버튼을 누르는 순간, 프론트엔드의 요청 → 백엔드 처리 → 응답 → 화면 업데이트라는 흐름이 빠르게 진행됩니다
- 카카오 로그인처럼, 잘 만들어진 기능을 API 형태로 연결해서 다른 서비스에서 활용하는 것도 API의 중요한 역할입니다
- API 문서는 개발자가 "어떤 형식으로 요청하고, 어떤 응답을 받을지"를 정확히 알 수 있도록 명세하는 것이 핵심입니다
다음 글에서는 백엔드가 처리한 데이터가 어디에 저장되는지, 즉 데이터베이스와 클라우드에 대해 이야기해보겠습니다. 회원가입을 할 때 내 정보가 어디로 가는지, 주문 내역은 어떻게 남아있는지, 그 이야기를 함께 풀어보겠습니다.
읽어주셔서 감사합니다.
'시즌 1 | 기초 기술 개념' 카테고리의 다른 글
| 좋은 기술문서는 왜 사람을 덜 헤매게 할까: 사용자 설명서와 API 문서의 차이 (0) | 2026.06.10 |
|---|---|
| 내 정보는 어디에 저장될까: 데이터베이스와 클라우드를 처음부터 (0) | 2026.06.10 |
| 웹과 앱은 무엇이 다를까: 프론트엔드와 백엔드까지 한 번에 이해하기 (0) | 2026.05.15 |
| 컴퓨터 언어란 무엇인가: C, Java, Python을 쉬운 비유로 설명하기 (1) | 2026.05.15 |
| 노베이스 비전공 테크니컬 라이터가 DevRel을 준비하는 이유 (0) | 2026.05.10 |