프론트 개발자를 위한 개발 용어 가이드 : API 통신편

GDG on Campus Gachon·2025년 9월 14일

API cors http json 백엔드 주니어개발자 프론트엔드 핵심용어

GDGoC Gachon Impact

목록 보기

11/18

백엔드 개발자와의 대화가 끝나면, 대화 내용을 복기하며 몰래 구글을 켜본 적 있나요?

대화 시점에서는 반사적으로 고개를 끄덕였지만, 사실 머릿속은 온통 물음표로 가득했던 순간들. 이런 경험은 저 역시 마찬가지였습니다. 프론트엔드 개발 공부에 집중할수록, 백엔드와 제대로 소통하지 못하면 반쪽짜리 개발자가 될 수밖에 없다는 것을 깨달았기 때문입니다.

그래서 이 글을 썼습니다.

‘API 통신’이라는 이름으로, 백엔드 개발자와 자신감 있게 소통하기 위해 알아야 할 ‘최소한의 약속과 용어’들을 정리했습니다.

더 이상 대화 내용을 복기하며 몰래 검색창을 켜는 대신, 당당하게 질문하고 함께 문제를 해결하는 개발자로 나아가는 첫걸음이 되기를 바랍니다.

저는 스스로를 '화면을 그리는 사람'이라고 생각했습니다. React로 나만의 컴포넌트를 만들고, 사용자의 인터랙션에 생명을 불어넣고 어떻게든 돌아간다면 된다는 생각뿐이었죠.

첫 협업을 하기 직전까지 말입니다. 첫 협업의 경험은 그런 저의 오만한 착각을 깨부수는 과정의 연속이었습니다.

나: "로그인 API가 너무 느려요."
백엔드 : "속도보다 안정성이 중요해요. 토큰 검증 로직 때문에 어쩔 수 없어요."

분명 같은 '로그인 기능'을 이야기하고 있었지만, 서로 다른 세계의 언어로 대화하고 있었습니다. 저는 '사용자'를 중심으로, 백엔드는 '서버의 안정성'을 이야기하고 있었죠.

그때 깨달았습니다. 좋은 프론트엔드 개발자는 단순히 그림만 잘 그리는 사람이 아니라, 데이터가 만들어지는 서버을 이해하고 그곳의 언어를 번역할 줄 아는 사람이라는 것을요.

1. 통신의 시작: 문을 두드리는 방법

협업의 시작은 백엔드라는 집에 찾아가 문을 두드리는 것과 같습니다. 하지만 무작정 찾아가 "데이터 주세요!"라고 외칠 순 없죠. 정확한 주소를 알고, 올바른 방법으로 문을 두드려야 합니다.

API Endpoint: 처음에는 그냥 URL인 줄 알았습니다. 하지만 엔드포인트는 단순히 example.com 같은 주소가 아니라, /users/123처럼 매우 구체적인 주소였습니다. 백엔드 개발자에게 이 정확한 주소를 물어보는 것이 소통의 첫걸음입니다.
HTTP Method: 문을 두드리는 것에도 목적이 필요합니다. 단순히 '안에 있는 서류를 보기 위함(GET)'인지, '새로운 서류를 제출하기 위함(POST)'인지, '기존 서류를 수정하기 위함(PUT/PATCH)'인지 명확히 밝혀야 합니다. 잘못된 방법으로 문을 두드리면 당연히 문은 열리지 않겠죠.

2. 대화의 형식: 어떤 내용를 주고받을 것인가

문을 제대로 두드렸다면, 이제 약속된 형식에 맞춰 서류를 주고받아야 합니다.

JSON: "응답은 JSON으로 드릴게요." 백엔드 동료의 이 말은 "앞으로 우리는 'A4용지 표준 양식'으로만 서류를 주고받을 겁니다"라는 약속과 같습니다. JavaScript에서 다루기 매우 쉬운 이 표준 양식 덕분에, 우리는 서버가 어떤 구조로 데이터를 주는지 예측하고 그에 맞춰 화면을 준비할 수 있습니다.
Request Body & Header: 내가 보내는 서류에도 규칙이 있습니다. 바디(Body)는 내가 전달하고 싶은 회원가입 정보 등 입니다. 그리고 헤더(Header)는 그 서류를 감싼 봉투와 같아서, ['발신인: OOO (인증 토큰)', '내용물 형식: JSON'] 같은 중요한 정보를 담아 서버가 내 요청을 오해 없이 처리하도록 돕습니다.

3. 응답의 의미: 서버를 읽는 기술

요청을 보낸 뒤 서버가 보내는 응답은 단순한 데이터 덩어리가 아닙니다. 거기에는 현재 서버의 상태와 내 요청에 대한 평가가 담겨있습니다.

HTTP Status Codes(상태 코드) : 처음 404 Not Found 에러를 만났을 때, 저는 서버가 고장 난 줄 알고 백엔드 동료를 다그쳤습니다. 하지만 그건 제 잘못이었습니다. 400번대 에러는 "요청에 문제가 있습니다"라는 뜻이고, 500번대 에러가 바로 "서버에 문제가 생겼습니다"라는 의미였죠. 이 숫자 언어를 이해하는 순간, 문제가 어디에 있는지 빠르게 파악하고 진짜 해결책을 찾을 수 있게 되었습니다.
CORS 에러: React나 Vue 등을 사용하여 프론트를 개발할 때, 클라이언트 서버와 API 서버가 같은 호스트에서 서로 다른 포트를 사용하게 되는 경우가 생겼는데, 이때 클라이언트 서버가 API 서버를 호출하는 과정에서 CORS 에러가 발생했습니다. 이 경우엔 백엔드에서 들어오도록 요청을 허용하거나 Proxy 서버를 사용해 해결할 수 있었습니다.