API와 JSON을 메뉴판과 주문서처럼 읽는 첫 연습

날씨, 지도, 결제, 번역 기능을 처음부터 모두 만들 필요는 없습니다. 이미 그 기능을 운영하는 서비스가 정해진 방법으로 요청을 받는다면 우리 프로그램이 그 창구를 이용할 수 있습니다. 그 창구가 API입니다.

API 설명서를 메뉴판, 요청을 주문서, 응답을 주방에서 돌아온 결과라고 생각해 보세요. 어떤 주소로 무엇을 보내야 하고 어떤 모양의 결과가 오는지만 읽어도 연동 작업의 절반은 이해한 셈입니다.

API는 프로그램끼리 대화하는 약속이다

API는 Application Programming Interface의 줄임말입니다. 브라우저 기능을 다루는 API도 있고, 다른 회사의 데이터나 기능을 네트워크로 호출하는 API도 있습니다. 실무에서 "API를 붙인다"고 말할 때는 대개 후자를 뜻합니다.

예를 들어 날씨 API는 도시 이름이나 좌표를 받으면 현재 기온과 예보를 돌려줍니다. 결제 API는 금액과 주문 정보를 받아 결제 절차를 시작합니다. 서비스마다 주소, 요청 방식, 필요한 권한, 응답 모양이 다르므로 반드시 공식 문서를 읽어야 합니다.

엔드포인트와 메서드가 주문 창구를 정한다

API 주소의 특정 경로를 엔드포인트라고 부릅니다. 같은 서비스라도 /weather/current는 현재 날씨, /weather/forecast는 예보처럼 역할이 나뉠 수 있습니다.

HTTP 메서드는 그 창구에서 할 일을 나타냅니다. GET은 자료 조회, POST는 새 작업 생성, PATCH는 일부 수정, DELETE는 삭제에 흔히 사용됩니다. 실제 의미는 API 문서가 정하므로 이름만 보고 중요한 요청을 보내면 안 됩니다.

• 요청 URL이 개발용인지 실제 운영용인지 확인합니다.
• 필요한 메서드가 무엇인지 확인합니다.
• 로그인 토큰이나 API 키가 필요한지 확인합니다.
• 초당 또는 하루 호출 제한이 있는지 확인합니다.
• 실패했을 때 다시 보내도 중복 결제가 생기지 않는지 확인합니다.

JSON은 이름과 값을 짝지어 보내는 텍스트다

많은 웹 API는 JSON 형식으로 데이터를 주고받습니다. JSON은 구조화된 데이터를 표현하는 텍스트 형식입니다. JavaScript 문법과 닮았지만 특정 언어에만 묶여 있지 않아 여러 환경에서 읽을 수 있습니다.

{
  "city": "Seoul",
  "temperature": 27,
  "unit": "celsius",
  "rain": false,
  "alerts": ["heat"]
}

중괄호는 하나의 객체를 뜻합니다. city 같은 왼쪽 이름을 키, Seoul 같은 오른쪽 내용을 값이라고 부릅니다. 문자열은 큰따옴표로 감싸고, 숫자와 참·거짓은 따옴표 없이 씁니다. 대괄호는 여러 값을 순서대로 담는 배열입니다.

temperature를 읽으려면 JavaScript에서 data.temperature처럼 접근할 수 있습니다. JSON 텍스트를 프로그램 객체로 바꾸는 과정은 파싱, 객체를 다시 JSON 텍스트로 바꾸는 과정은 직렬화라고 부릅니다.

성공 응답만 가정하면 실제 서비스에서 멈춘다

초보 예제는 정상 JSON만 보여 주는 경우가 많습니다. 실제 API는 키가 틀리거나, 사용량을 넘기거나, 서버가 잠시 불안정할 수 있습니다. 상태 코드와 오류 본문을 함께 처리해야 합니다.

1. 200 계열이면 필요한 필드가 실제로 있는지 확인합니다.
2. 400이면 보낸 값과 JSON 형식을 확인합니다.
3. 401이면 키나 로그인 토큰을 확인합니다.
4. 403이면 해당 기능을 쓸 권한이 있는지 확인합니다.
5. 429이면 호출 제한과 재시도 간격을 확인합니다.
6. 500 계열이면 무한 재시도하지 말고 잠시 뒤 제한적으로 다시 시도합니다.

응답이 성공이어도 원하는 필드가 없을 수 있습니다. temperature가 항상 온다고 믿지 말고, 없을 때 화면에 "현재 기온을 불러오지 못했습니다"처럼 설명할 준비가 필요합니다.

API 키는 프론트엔드 코드에 그대로 넣지 않는다

브라우저로 전달된 JavaScript는 사용자가 볼 수 있습니다. 비밀 API 키를 프론트엔드 코드에 적으면 화면에 보이지 않아도 개발자 도구나 내려받은 파일에서 찾을 수 있습니다.

비밀 키가 필요한 요청은 보통 백엔드가 대신 보냅니다. 브라우저는 내 서버에 필요한 값만 요청하고, 서버가 안전하게 보관한 키로 외부 API를 호출한 뒤 필요한 결과만 돌려줍니다. 공개용 키라면 허용 도메인과 권한을 제한하고, 서비스 문서의 보안 지침을 따릅니다.

AI에게 API 연동을 부탁할 때 줄 정보

"날씨 API 붙여 줘"보다 계약을 명확히 적어야 합니다.

기능: 서울 현재 기온 표시
요청: GET /weather/current, query는 city=Seoul
성공 응답: temperature 숫자와 unit 문자열
오류 처리: 401, 429, 500을 서로 다른 메시지로 표시
보안: 비밀 키는 서버 환경변수에 보관
검증: 키 없음, 느린 응답, 필드 누락, 모바일 화면 테스트

오늘 바로 해볼 작은 실습

실제 키가 필요 없는 공개 예제 JSON 하나를 브라우저에서 열어 보세요. 중괄호 안에서 문자열, 숫자, 참·거짓, 배열을 각각 하나씩 찾습니다. 그다음 "이 응답에서 화면에 보여 줄 값은 무엇인가"를 세 줄로 적어 봅니다.

1. 주소창에 보이는 API 경로를 기록합니다.
2. 가장 바깥쪽 값이 객체인지 배열인지 확인합니다.
3. 화면에 필요한 키 이름을 두 개 고릅니다.
4. 그 키가 없을 때 보여 줄 문장을 적습니다.
5. 상태 코드가 200이 아닐 때 어떤 안내가 필요한지 정합니다.

마지막으로 공식 문서의 예제 응답을 복사해 AI에게 함께 주되 실제 키는 넣지 않습니다. 생성된 코드가 문서의 주소, 메서드, 필드 이름과 맞는지 대조합니다. API 연동은 코드를 많이 아는 문제라기보다 약속을 정확히 읽고 실패 경우를 빠뜨리지 않는 문제에 더 가깝습니다.