API 개념과 JSON 데이터 완벽 가이드

초급 개발자를 위한 API와 JSON 데이터 기초부터 실전 활용까지. REST API 개념, HTTP 메서드, JSON 데이터 구조를 실무 스토리로 쉽게 배웁니다.

1. API란 무엇인가?

신입 개발자 김개발 씨는 오늘도 회의실에서 선배들의 대화를 듣고 있었습니다. "이 기능은 외부 API 연동하면 금방이에요." 김개발 씨는 고개를 끄덕였지만, 사실 API가 정확히 무엇인지 잘 몰랐습니다.

회의가 끝나고 책상으로 돌아온 김개발 씨는 검색창에 "API란 무엇인가"를 입력했습니다.

API(Application Programming Interface)는 프로그램끼리 소통하는 약속된 방법입니다. 마치 식당에서 메뉴판을 보고 주문하는 것처럼, API는 프로그램이 다른 프로그램에게 "이런 작업을 해주세요"라고 요청할 수 있게 해줍니다.

복잡한 내부 구조를 몰라도 정해진 방법으로 원하는 기능을 사용할 수 있습니다.

다음 코드를 살펴봅시다.

import requests

# 날씨 API에 요청을 보냅니다
url = "https://api.weatherapi.com/v1/current.json"
params = {
    "key": "your_api_key",
    "q": "Seoul"
}

# API 호출
response = requests.get(url, params=params)

# 응답 받기
weather_data = response.json()
print(f"서울 날씨: {weather_data['current']['temp_c']}도")

김개발 씨는 입사 2주 차 신입 개발자입니다. 오늘 팀장님께서 "날씨 정보를 보여주는 기능을 추가해보세요"라는 업무를 주셨습니다.

김개발 씨는 당황했습니다. 날씨 데이터를 어떻게 구하지?

옆자리 선배 박시니어 씨가 말했습니다. "날씨 API 쓰면 돼요.

간단해요." 그렇다면 API란 정확히 무엇일까요? API를 이해하는 가장 쉬운 방법은 식당의 메뉴판과 종업원을 떠올리는 것입니다.

손님인 여러분은 주방이 어떻게 생겼는지, 요리사가 어떤 방법으로 요리하는지 알 필요가 없습니다. 그저 메뉴판을 보고 "김치찌개 하나요"라고 주문하면 됩니다.

종업원이 주문을 받아 주방에 전달하고, 완성된 요리를 가져다줍니다. API도 이와 똑같습니다.

여러분의 프로그램은 손님이고, 다른 회사의 서비스는 주방입니다. API는 메뉴판이자 종업원 역할을 합니다.

API가 없던 시절에는 어땠을까요? 모든 기능을 직접 만들어야 했습니다.

날씨 정보가 필요하면 기상청 데이터베이스에 직접 접근해서 복잡한 처리를 거쳐야 했습니다. 지도 기능이 필요하면 지도 데이터를 직접 수집하고 렌더링 엔진을 개발해야 했습니다.

이런 작업은 수개월에서 수년이 걸렸습니다. 더 큰 문제는 보안과 유지보수였습니다.

다른 회사의 시스템에 직접 접근하려면 복잡한 권한 설정이 필요했고, 데이터 구조가 바뀔 때마다 코드를 전부 수정해야 했습니다. 바로 이런 문제를 해결하기 위해 API가 등장했습니다.

API를 사용하면 복잡한 내부 구조를 몰라도 됩니다. 정해진 주소(URL)로 요청을 보내고, 약속된 형식으로 응답을 받으면 끝입니다.

또한 보안도 간단해집니다. API 키라는 일종의 출입증만 받으면 안전하게 데이터를 주고받을 수 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 requests 라이브러리를 불러옵니다.

이것은 Python에서 API 요청을 보낼 때 가장 많이 사용하는 도구입니다. 다음으로 API 주소(url)를 설정합니다.

이것이 바로 "어디에 요청을 보낼지"를 정하는 부분입니다. 그리고 params에 필요한 정보를 담습니다.

API 키와 도시 이름을 전달합니다. requests.get()으로 실제 요청을 보내고, response.json()으로 응답을 받아옵니다.

실제 현업에서는 어떻게 활용할까요? 쇼핑몰 서비스를 개발한다고 가정해봅시다.

결제 기능이 필요하면 토스페이먼츠 API를 사용하고, 배송 조회가 필요하면 택배사 API를 연동하고, 상품 추천이 필요하면 AI 추천 API를 사용합니다. 각 기능을 직접 개발하는 대신 API로 연결하면 몇 시간 만에 완성할 수 있습니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 API 키를 코드에 그대로 적어두는 것입니다.

API 키는 출입증과 같아서 다른 사람이 알게 되면 여러분의 계정으로 무단 사용될 수 있습니다. 따라서 환경변수나 별도 설정 파일에 보관해야 합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다.

"아, API는 다른 프로그램의 기능을 빌려 쓰는 거군요!" API를 제대로 이해하면 개발 속도가 비약적으로 빨라집니다. 필요한 기능을 직접 만드는 대신 검증된 API를 활용하세요.

여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - API 키는 절대 코드에 직접 쓰지 말고 환경변수로 관리하세요

무료 API는 호출 횟수 제한이 있으니 문서를 꼭 확인하세요
API 응답은 항상 예외 처리를 해두어야 안전합니다

2. REST API 개념 이해

김개발 씨는 API 문서를 읽다가 "RESTful API"라는 단어를 발견했습니다. API는 알겠는데, REST는 또 뭘까요?

박시니어 씨에게 물어보니 "요즘 API는 대부분 REST 방식이에요"라고 답했습니다. 김개발 씨는 REST API가 무엇인지 제대로 알아보기로 했습니다.

REST API는 웹의 장점을 최대한 활용하는 API 설계 방식입니다. 마치 도서관에서 책을 분류하듯이, 자원(데이터)을 URL로 표현하고 HTTP 메서드로 동작을 정의합니다.

GET으로 조회하고, POST로 생성하고, PUT으로 수정하고, DELETE로 삭제하는 직관적인 구조입니다.

다음 코드를 살펴봅시다.

import requests

# REST API 기본 구조
base_url = "https://api.example.com"

# 사용자 목록 조회 (GET)
response = requests.get(f"{base_url}/users")
users = response.json()

# 특정 사용자 조회 (GET)
user_id = 123
response = requests.get(f"{base_url}/users/{user_id}")
user = response.json()

# 새 사용자 생성 (POST)
new_user = {"name": "김개발", "email": "kim@example.com"}
response = requests.post(f"{base_url}/users", json=new_user)

김개발 씨는 회사에서 사용자 관리 API를 만드는 업무를 받았습니다. 선배에게 참고할 만한 코드를 부탁하니 "REST 원칙을 따라서 만들어보세요"라는 답변이 돌아왔습니다.

김개발 씨는 당황했습니다. 그날 저녁, 김개발 씨는 REST API에 대해 공부하기 시작했습니다.

REST를 이해하는 가장 좋은 비유는 도서관입니다. 도서관에서 책을 찾을 때를 생각해보세요.

"문학 -> 한국 소설 -> ㄱ -> 김유정"처럼 계층적으로 위치를 표현합니다. 그리고 "책 빌리기", "책 반납하기", "책 예약하기"처럼 동작도 명확하게 구분됩니다.

REST API도 똑같습니다. 자원의 위치를 URL로 표현하고, 동작을 HTTP 메서드로 구분합니다.

REST가 등장하기 전에는 어땠을까요? 각 회사마다 API를 제멋대로 만들었습니다.

어떤 회사는 /getUserList라는 주소를 사용하고, 다른 회사는 /getUsers를 사용했습니다. 같은 기능인데도 회사마다 이름과 방식이 달라서 개발자들은 매번 새로운 API를 배워야 했습니다.

더 큰 문제는 일관성 부족이었습니다. 사용자를 조회할 때는 GET을 쓰다가, 삭제할 때는 POST를 쓰는 식으로 혼란스러웠습니다.

API 문서를 하나하나 읽어봐야만 사용법을 알 수 있었습니다. 바로 이런 혼란을 정리하기 위해 REST 원칙이 등장했습니다.

REST를 따르면 API가 직관적이 됩니다. /users는 사용자 목록을, /users/123은 123번 사용자를 의미한다는 것을 누구나 알 수 있습니다.

또한 HTTP 메서드만 보면 무슨 동작인지 알 수 있습니다. GET은 조회, POST는 생성, PUT은 수정, DELETE는 삭제입니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 기본 URL을 설정합니다.

이것은 API 서버의 주소입니다. /users로 요청을 보내면 모든 사용자 목록을 받아옵니다.

이것이 컬렉션(collection) 개념입니다. /users/123처럼 특정 ID를 붙이면 개별 사용자 정보를 받아옵니다.

이것이 리소스(resource) 개념입니다. 새 사용자를 만들 때는 POST 메서드를 사용합니다.

데이터를 json 파라미터로 전달하면 서버가 새 사용자를 생성합니다. 실제 현업에서는 어떻게 활용할까요?

블로그 서비스를 만든다고 가정해봅시다. 게시글은 /posts로, 댓글은 /posts/123/comments로 표현합니다.

계층 구조가 명확하죠. 사용자가 게시글을 작성하면 POST, 수정하면 PUT, 삭제하면 DELETE를 사용합니다.

이렇게 REST 원칙을 따르면 API 문서가 없어도 대략적인 사용법을 짐작할 수 있습니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수는 URL에 동사를 넣는 것입니다. /getUsers, /createUser처럼 말이죠.

REST에서는 URL은 자원만 표현하고, 동작은 HTTP 메서드로 표현해야 합니다. 올바른 방식은 GET /users, POST /users입니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 다음 날 김개발 씨는 REST 원칙을 따라 API를 설계했습니다.

박시니어 씨가 코드 리뷰를 하더니 엄지를 들어 올렸습니다. "완벽해요!" REST API를 제대로 이해하면 누구나 이해하기 쉬운 API를 만들 수 있습니다.

일관된 규칙을 따르면 유지보수도 훨씬 쉬워집니다. 여러분도 오늘 배운 REST 원칙을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - URL에는 명사만, 동작은 HTTP 메서드로 표현하세요

계층 구조는 / 로 명확하게 나타내세요
버전 관리는 /v1/users 처럼 URL에 명시하는 것이 좋습니다

3. HTTP 메서드 (GET, POST)

김개발 씨는 API 개발을 하다가 궁금한 점이 생겼습니다. GET과 POST는 언제 쓰는 걸까요?

둘 다 데이터를 주고받는 건데 뭐가 다른 걸까요? 박시니어 씨에게 물어보니 "GET은 조회할 때, POST는 생성할 때 쓴다"고 간단히 설명해주었습니다.

하지만 김개발 씨는 더 깊이 알고 싶었습니다.

HTTP 메서드는 서버에게 "무엇을 할지" 알려주는 동사입니다. GET은 데이터를 가져올 때, POST는 새로운 데이터를 만들 때 사용합니다.

GET은 URL에 데이터가 보이지만 POST는 본문에 숨겨서 보냅니다. 또한 GET은 여러 번 호출해도 결과가 같지만, POST는 호출할 때마다 새로운 데이터가 생성됩니다.

다음 코드를 살펴봅시다.

import requests

# GET 요청 - 데이터 조회
# URL에 파라미터가 노출됩니다
params = {"page": 1, "size": 10}
response = requests.get("https://api.example.com/posts", params=params)
posts = response.json()
print(f"게시글 {len(posts)}개 조회됨")

# POST 요청 - 데이터 생성
# 데이터가 본문에 담겨서 전송됩니다
new_post = {
    "title": "API 공부 시작",
    "content": "오늘부터 API를 배웁니다",
    "author": "김개발"
}
response = requests.post("https://api.example.com/posts", json=new_post)
created = response.json()
print(f"게시글 ID {created['id']} 생성됨")

김개발 씨는 게시판 기능을 만들고 있었습니다. 게시글 목록을 보여주고, 새 게시글을 작성하는 기능이 필요했습니다.

두 기능 모두 서버와 통신해야 하는데, 어떤 메서드를 써야 할지 고민이 되었습니다. 박시니어 씨가 지나가다 말했습니다.

"목록 보기는 GET, 글 작성은 POST죠." 그렇다면 GET과 POST는 정확히 무엇이 다를까요? HTTP 메서드를 이해하는 좋은 비유는 도서관의 행동입니다.

도서관에서 책을 찾아보는 것은 GET입니다. 책장을 아무리 뒤져도 책이 없어지거나 바뀌지 않습니다.

반면 대출 신청서를 작성하는 것은 POST입니다. 신청서를 낼 때마다 새로운 대출 기록이 생깁니다.

GET과 POST를 구분하지 않던 시절에는 어땠을까요? 모든 요청을 POST로 처리하는 사이트들이 많았습니다.

게시글을 조회하는데도 POST를 쓰고, 검색하는데도 POST를 썼습니다. 이렇게 되면 브라우저의 뒤로가기 버튼을 눌렀을 때 "양식을 다시 제출하시겠습니까?"라는 경고창이 뜹니다.

사용자는 불안해집니다. 더 큰 문제는 캐싱입니다.

GET 요청은 브라우저가 결과를 저장해두었다가 재사용할 수 있습니다. 하지만 POST는 매번 서버에 새로 요청해야 합니다.

성능 차이가 크게 납니다. 바로 이런 이유로 GET과 POST를 명확히 구분해야 합니다.

GET을 사용하면 URL만 봐도 어떤 데이터를 요청하는지 알 수 있습니다. 브라우저 주소창에 ?page=1&size=10처럼 표시되기 때문입니다.

또한 URL을 복사해서 공유할 수 있습니다. 친구에게 "이 링크 봐봐"라고 보낼 수 있죠.

반면 POST는 데이터가 본문에 담겨서 전송됩니다. URL에는 보이지 않습니다.

로그인할 때 비밀번호가 주소창에 보이면 안 되겠죠? 또한 POST는 호출할 때마다 서버의 상태가 바뀝니다.

게시글을 작성하면 데이터베이스에 새 레코드가 추가됩니다. 위의 코드를 한 줄씩 살펴보겠습니다.

GET 요청에서는 params 딕셔너리로 파라미터를 전달합니다. requests 라이브러리가 자동으로 URL에 ?page=1&size=10을 붙여줍니다.

서버는 1페이지의 10개 게시글을 반환합니다. POST 요청에서는 json 파라미터로 데이터를 전달합니다.

이 데이터는 요청 본문에 JSON 형식으로 담깁니다. 서버는 새 게시글을 생성하고, 생성된 게시글의 ID를 반환합니다.

실제 현업에서는 어떻게 활용할까요? 쇼핑몰 서비스를 생각해봅시다.

상품 목록을 보여줄 때는 GET을 사용합니다. 사용자가 "파란색 신발"을 검색하면 URL이 /products?color=blue&category=shoes가 됩니다.

이 URL을 친구에게 공유할 수 있습니다. 반면 장바구니에 상품을 담을 때는 POST를 사용합니다.

버튼을 누를 때마다 장바구니에 항목이 추가되어야 하니까요. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수는 GET으로 데이터를 변경하려는 것입니다. 예를 들어 /deleteUser?id=123 같은 URL을 만드는 경우입니다.

이렇게 하면 누군가 이 링크를 클릭하거나, 검색 엔진이 크롤링하면 데이터가 삭제될 수 있습니다. 위험합니다.

데이터를 변경하는 작업은 반드시 POST나 DELETE를 써야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

김개발 씨는 게시판 기능을 완성했습니다. 목록 조회는 GET, 글 작성은 POST로 구현했습니다.

테스트해보니 완벽하게 작동했습니다. GET과 POST를 올바르게 사용하면 안전하고 효율적인 API를 만들 수 있습니다.

각 메서드의 특성을 이해하고 적재적소에 활용하세요. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - 데이터 조회는 GET, 생성/수정/삭제는 POST/PUT/DELETE를 사용하세요

GET 요청에는 민감한 정보를 담지 마세요
POST 요청 후에는 적절한 상태 코드(201 Created)를 반환하세요

4. JSON 데이터 구조

김개발 씨는 API 응답을 받고 나서 당황했습니다. 화면에 뭔가 이상한 텍스트가 출력되었습니다.

중괄호와 대괄호가 가득한 문자열이었습니다. 박시니어 씨가 웃으며 말했습니다.

"그게 JSON이에요. API는 대부분 JSON으로 데이터를 주고받아요." 김개발 씨는 JSON이 무엇인지 알아보기로 했습니다.

JSON(JavaScript Object Notation)은 데이터를 주고받을 때 사용하는 텍스트 형식입니다. 마치 엑셀 표를 텍스트로 표현한 것처럼, 구조화된 데이터를 중괄호와 대괄호로 나타냅니다.

사람이 읽기 쉽고, 프로그램이 처리하기도 쉬워서 API의 표준 형식이 되었습니다.

다음 코드를 살펴봅시다.

import json

# JSON 문자열 (API에서 받은 응답)
json_string = '''
{
    "user": {
        "id": 123,
        "name": "김개발",
        "email": "kim@example.com",
        "skills": ["Python", "JavaScript", "API"],
        "is_active": true
    }
}
'''

# JSON을 Python 딕셔너리로 변환
data = json.loads(json_string)
print(f"사용자 이름: {data['user']['name']}")
print(f"보유 스킬: {', '.join(data['user']['skills'])}")

# Python 객체를 JSON 문자열로 변환
new_user = {"id": 456, "name": "박시니어", "level": 5}
json_output = json.dumps(new_user, ensure_ascii=False, indent=2)
print(json_output)

김개발 씨는 사용자 정보를 가져오는 API를 호출했습니다. 응답이 왔지만 형식이 낯설었습니다.

중괄호 안에 이름, 이메일, 스킬 목록이 담겨 있었습니다. "이걸 어떻게 사용하지?" 박시니어 씨가 설명했습니다.

"JSON은 데이터 형식이에요. Python 딕셔너리랑 비슷해요." 그렇다면 JSON은 정확히 무엇일까요?

JSON을 이해하는 가장 좋은 비유는 택배 송장입니다. 택배를 보낼 때 "보내는 사람: 김개발, 받는 사람: 박시니어, 주소: 서울시..."처럼 정보를 구조화해서 적습니다.

JSON도 똑같습니다. 데이터를 "이름: 값" 형식으로 정리해서 전달합니다.

JSON이 등장하기 전에는 어땠을까요? XML이라는 복잡한 형식을 사용했습니다.

XML은 태그가 많아서 같은 데이터를 표현해도 용량이 2-3배 컸습니다. 또한 사람이 읽기 어려웠습니다.

태그의 시작과 끝을 일일이 확인해야 했으니까요. 더 큰 문제는 파싱(해석)이 복잡했다는 것입니다.

XML을 읽으려면 특별한 라이브러리가 필요했고, 코드도 길어졌습니다. 단순히 사용자 이름을 가져오는데도 여러 줄의 코드가 필요했습니다.

바로 이런 불편함을 해결하기 위해 JSON이 등장했습니다. JSON은 JavaScript 객체 표기법에서 유래했지만, 지금은 모든 프로그래밍 언어에서 지원합니다.

Python에서는 딕셔너리와 리스트로 자연스럽게 변환됩니다. 중괄호는 딕셔너리, 대괄호는 리스트를 의미합니다.

또한 JSON은 타입을 명확히 구분합니다. 문자열은 큰따옴표로 감싸고, 숫자는 그대로 쓰고, 불린은 true/false로 표현합니다.

null도 지원합니다. 위의 코드를 한 줄씩 살펴보겠습니다.

먼저 API에서 받은 JSON 문자열이 있습니다. 이것은 그냥 텍스트입니다.

json.loads() 함수로 이 텍스트를 Python 딕셔너리로 변환합니다. 그러면 data['user']['name']처럼 접근할 수 있습니다.

반대로 Python 객체를 JSON 문자열로 만들 때는 json.dumps()를 사용합니다. ensure_ascii=False는 한글이 깨지지 않게 하는 옵션이고, indent=2는 보기 좋게 들여쓰기를 추가하는 옵션입니다.

실제 현업에서는 어떻게 활용할까요? 웹 서비스를 만들 때 프론트엔드와 백엔드는 JSON으로 대화합니다.

사용자가 회원가입 폼을 작성하면 프론트엔드가 입력값을 JSON으로 만들어 서버에 보냅니다. 서버는 처리 결과를 JSON으로 응답합니다.

모바일 앱도 마찬가지입니다. JSON은 사실상 웹 통신의 표준 언어가 되었습니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수는 JSON 형식을 잘못 만드는 것입니다.

큰따옴표 대신 작은따옴표를 쓰거나, 마지막 항목 뒤에 쉼표를 붙이면 에러가 납니다. JSON은 형식이 엄격합니다.

또한 딕셔너리의 키는 반드시 문자열이어야 합니다. 숫자나 불린은 키가 될 수 없습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 JSON을 딕셔너리로 변환하는 방법을 배웠습니다.

이제 API 응답을 자유자재로 다룰 수 있게 되었습니다. JSON을 제대로 이해하면 API 개발과 데이터 처리가 훨씬 수월해집니다.

대부분의 현대 API가 JSON을 사용하니 필수로 알아야 하는 지식입니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - JSON 형식이 올바른지 확인하려면 jsonlint.com 같은 검증 도구를 사용하세요

큰 JSON 데이터는 indent 옵션으로 보기 좋게 출력하세요
JSON은 주석을 지원하지 않으니 설명이 필요하면 별도 문서를 작성하세요

5. JSON vs CSV 비교

김개발 씨는 데이터를 파일로 저장해야 하는 업무를 받았습니다. 박시니어 씨가 물었습니다.

"JSON으로 저장할래요, CSV로 저장할래요?" 김개발 씨는 두 형식의 차이를 몰랐습니다. 언제 JSON을 쓰고 언제 CSV를 써야 하는 걸까요?

JSON은 계층 구조가 있는 복잡한 데이터에 적합하고, CSV는 표 형태의 단순한 데이터에 적합합니다. JSON은 중첩된 객체와 배열을 표현할 수 있지만, CSV는 행과 열로만 데이터를 표현합니다.

JSON은 API 통신에, CSV는 엑셀 데이터 교환에 주로 사용됩니다.

다음 코드를 살펴봅시다.

import json
import csv

# 같은 데이터를 JSON과 CSV로 표현

# JSON 형식 - 계층 구조 표현 가능
users_json = [
    {
        "id": 1,
        "name": "김개발",
        "skills": ["Python", "API"],  # 배열 가능
        "address": {  # 중첩 객체 가능
            "city": "서울",
            "district": "강남구"
        }
    }
]

with open("users.json", "w", encoding="utf-8") as f:
    json.dump(users_json, f, ensure_ascii=False, indent=2)

# CSV 형식 - 평면 구조만 가능
users_csv = [
    ["id", "name", "skills", "city", "district"],
    [1, "김개발", "Python;API", "서울", "강남구"]  # 배열은 문자열로 변환
]

with open("users.csv", "w", encoding="utf-8", newline="") as f:
    writer = csv.writer(f)
    writer.writerows(users_csv)

김개발 씨는 사용자 데이터 100명분을 파일로 저장해야 했습니다. 각 사용자는 이름, 이메일, 보유 스킬, 주소 정보를 가지고 있었습니다.

어떤 형식으로 저장해야 할까요? 박시니어 씨가 조언했습니다.

"데이터 구조를 보고 결정하세요." 그렇다면 JSON과 CSV는 각각 언제 사용해야 할까요? 두 형식을 비교하는 좋은 비유는 책과 표입니다.

소설책은 챕터 안에 섹션이 있고, 섹션 안에 문단이 있는 계층 구조입니다. 이것이 JSON입니다.

반면 시간표는 행과 열로 이루어진 평면 구조입니다. 이것이 CSV입니다.

두 형식이 공존하게 된 이유는 무엇일까요? 초기에는 CSV가 주로 쓰였습니다.

데이터베이스 테이블을 그대로 텍스트로 옮기기 좋았으니까요. 엑셀에서 열고 수정하기도 쉬웠습니다.

하지만 웹 서비스가 발전하면서 데이터가 복잡해졌습니다. 사용자 한 명이 여러 개의 스킬을 가지고, 주소도 시/구/동으로 나뉘는 식으로요.

CSV로는 이런 계층 구조를 표현하기 어려웠습니다. 배열을 세미콜론으로 구분하거나, 주소를 한 칸에 몰아 넣어야 했습니다.

데이터를 다시 읽을 때 파싱이 복잡해졌습니다. 바로 이런 문제를 해결하기 위해 JSON이 선호되기 시작했습니다.

JSON은 중첩된 객체를 자연스럽게 표현합니다. 사용자의 주소가 address 객체 안에 city와 district를 가지는 식으로 말이죠.

스킬 목록도 진짜 배열로 저장할 수 있습니다. 데이터를 읽을 때도 user['address']['city']처럼 직관적으로 접근할 수 있습니다.

반면 CSV의 장점은 단순함입니다. 엑셀이나 구글 시트에서 바로 열 수 있습니다.

비개발자도 쉽게 데이터를 확인하고 수정할 수 있습니다. 또한 용량이 작습니다.

같은 데이터를 JSON으로 저장하면 중괄호와 키 이름 때문에 용량이 커집니다. 위의 코드를 한 줄씩 살펴보겠습니다.

JSON으로 저장할 때는 json.dump()를 사용합니다. Python 리스트와 딕셔너리를 그대로 전달하면 자동으로 JSON 형식으로 변환됩니다.

계층 구조가 그대로 유지됩니다. CSV로 저장할 때는 csv.writer()를 사용합니다.

첫 번째 행은 헤더(컬럼 이름)입니다. 그다음 행부터 데이터를 씁니다.

배열인 스킬은 세미콜론으로 연결해서 하나의 문자열로 만들어야 합니다. 중첩 객체인 주소는 평면화해서 각 필드를 별도 컬럼으로 분리합니다.

실제 현업에서는 어떻게 선택할까요? API 응답은 거의 항상 JSON입니다.

웹과 모바일 앱이 서버와 통신할 때는 JSON이 표준입니다. 설정 파일도 JSON이 많이 쓰입니다.

반면 데이터 분석 팀과 협업할 때는 CSV를 많이 사용합니다. 분석가들은 엑셀이나 파이썬 pandas로 CSV를 쉽게 다룰 수 있으니까요.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수는 복잡한 데이터를 억지로 CSV에 우겨 넣는 것입니다.

배열을 세미콜론으로 구분하고, 중첩 객체를 JSON 문자열로 변환해서 한 칸에 넣는 식으로요. 이렇게 하면 나중에 읽을 때 파싱이 복잡해지고 버그가 생기기 쉽습니다.

복잡한 구조는 처음부터 JSON을 쓰는 것이 좋습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

김개발 씨는 데이터 구조를 살펴보고 JSON을 선택했습니다. 사용자마다 보유 스킬 개수가 달랐고, 주소 정보도 계층 구조였기 때문입니다.

JSON과 CSV의 특성을 이해하면 상황에 맞는 형식을 선택할 수 있습니다. 복잡한 구조는 JSON, 단순한 표는 CSV로 저장하세요.

여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - 데이터 구조가 복잡하면 JSON, 단순하면 CSV를 선택하세요

비개발자와 협업할 때는 CSV가 편리합니다
CSV는 쉼표가 데이터에 포함되면 문제가 생기니 주의하세요

6. API 문서 읽는 법

김개발 씨는 회사에서 새로운 결제 API를 연동하는 업무를 받았습니다. API 문서를 열어보니 수십 페이지에 달하는 영어 설명이 나왔습니다.

어디서부터 읽어야 할지 막막했습니다. 박시니어 씨가 조언했습니다.

"API 문서는 읽는 순서가 있어요."

API 문서는 API 사용 설명서입니다. 기본 URL, 인증 방법, 엔드포인트 목록, 요청/응답 예시로 구성됩니다.

처음에는 인증 섹션과 빠른 시작 가이드를 먼저 읽고, 필요한 엔드포인트만 찾아서 읽는 것이 효율적입니다. 모든 페이지를 읽으려 하지 마세요.

다음 코드를 살펴봅시다.

import requests

# API 문서에서 찾아야 할 정보들
# 1. 기본 URL (Base URL)
base_url = "https://api.example.com/v1"

# 2. 인증 방법 (API Key, Bearer Token 등)
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}

# 3. 엔드포인트와 메서드
# 문서: GET /users/{id} - 특정 사용자 조회
user_id = 123
response = requests.get(f"{base_url}/users/{user_id}", headers=headers)

# 4. 응답 형식 확인
if response.status_code == 200:
    user = response.json()
    print(f"이름: {user['name']}")
else:
    # 5. 에러 코드 처리
    print(f"에러 {response.status_code}: {response.text}")

김개발 씨는 토스페이먼츠 API 문서를 펼쳐 놓았습니다. 목차만 봐도 수십 개 항목이 있었습니다.

"이걸 다 읽어야 하나?" 김개발 씨는 막막했습니다. 박시니어 씨가 모니터를 보며 말했습니다.

"문서 전체를 읽을 필요는 없어요. 필요한 부분만 찾아 읽으면 돼요." 그렇다면 API 문서를 효율적으로 읽는 방법은 무엇일까요?

API 문서를 읽는 것은 마치 여행 가이드북을 읽는 것과 같습니다. 파리 여행을 간다고 가이드북을 첫 페이지부터 끝까지 읽지는 않죠.

지도를 보고 교통 정보를 확인한 다음, 가고 싶은 장소만 찾아서 읽습니다. API 문서도 똑같습니다.

API 문서가 잘 정리되지 않았던 시절에는 어땠을까요? 개발자들은 서버 개발자에게 직접 물어봐야 했습니다.

"이 API 어떻게 호출해요?", "에러 코드 400은 무슨 뜻이에요?" 같은 질문을 반복했습니다. 커뮤니케이션 비용이 컸고, 서버 개발자는 계속 같은 질문에 답해야 했습니다.

더 큰 문제는 외부 API를 사용할 때였습니다. 문서가 없으면 시행착오로 API를 탐색해야 했습니다.

어떤 파라미터를 보내야 하는지, 응답이 어떤 형식인지 하나하나 테스트해봐야 했습니다. 바로 이런 비효율을 없애기 위해 잘 작성된 API 문서가 중요해졌습니다.

좋은 API 문서는 일정한 구조를 따릅니다. 첫째, 개요 섹션에서 API가 무엇을 하는지 설명합니다.

둘째, 인증 섹션에서 API 키를 받는 방법과 요청에 포함하는 방법을 알려줍니다. 셋째, 빠른 시작 가이드에서 5분 안에 첫 API 호출을 성공시킬 수 있게 도와줍니다.

그다음 엔드포인트 레퍼런스가 나옵니다. 이것이 문서의 대부분을 차지합니다.

하지만 처음부터 끝까지 읽을 필요는 없습니다. 필요한 기능의 엔드포인트만 찾아서 읽으면 됩니다.

각 엔드포인트 문서는 보통 이런 정보를 담고 있습니다. HTTP 메서드와 URL 경로, 필수/선택 파라미터 목록, 요청 예시, 성공 응답 예시, 에러 응답 예시가 그것입니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 문서에서 기본 URL을 찾아야 합니다.

보통 문서 첫 페이지나 인증 섹션에 나와 있습니다. 다음으로 인증 방법을 확인합니다.

API 키를 헤더에 넣는지, 파라미터로 보내는지 확인해야 합니다. 이 예제에서는 Bearer Token 방식입니다.

그다음 필요한 엔드포인트를 찾습니다. 사용자 정보를 가져오고 싶다면 "사용자 조회" 엔드포인트를 찾으면 됩니다.

문서에 GET /users/{id}라고 나와 있으면, {id} 부분을 실제 숫자로 바꿔서 요청하면 됩니다. 마지막으로 에러 처리를 확인합니다.

상태 코드가 200이 아니면 뭔가 문제가 있는 것입니다. 문서의 에러 코드 섹션을 보면 각 코드의 의미를 알 수 있습니다.

실제 현업에서는 어떻게 활용할까요? 새로운 API를 연동할 때 개발자들은 이런 순서로 작업합니다.

첫째, 빠른 시작 가이드를 따라 첫 호출에 성공합니다. 둘째, 필요한 기능의 엔드포인트 3-4개를 찾아서 자세히 읽습니다.

셋째, Postman 같은 도구로 실제 요청을 보내보고 응답을 확인합니다. 넷째, 코드로 구현합니다.

문서를 다 읽고 나서 코딩을 시작하는 것이 아니라, 필요한 부분만 읽으면서 동시에 개발을 진행합니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수는 문서를 대충 읽고 바로 코딩부터 하는 것입니다. 특히 인증 부분을 제대로 읽지 않아서 401 Unauthorized 에러를 계속 받는 경우가 많습니다.

또한 요청 예시는 보지만 응답 예시는 안 보는 실수도 많습니다. 응답 구조를 모르면 데이터를 제대로 파싱할 수 없습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언대로 김개발 씨는 인증 섹션과 결제 생성 엔드포인트만 집중해서 읽었습니다.

30분 만에 첫 결제 API 호출에 성공했습니다. API 문서를 효율적으로 읽는 방법을 알면 새로운 API 연동이 훨씬 빨라집니다.

전체를 읽으려 하지 말고, 필요한 부분만 찾아서 깊이 읽으세요. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - API 문서는 빠른 시작 가이드부터 따라 해보세요

Postman으로 문서의 예시를 직접 실행해보면 이해가 빠릅니다
잘 안 되면 문서의 FAQ나 커뮤니티를 확인하세요

7. 무료 공공 API 소개

김개발 씨는 포트폴리오 프로젝트를 만들고 싶었습니다. 하지만 데이터가 없었습니다.

박시니어 씨가 말했습니다. "공공 API 써보세요.

무료로 다양한 데이터를 쓸 수 있어요." 김개발 씨는 무료로 쓸 수 있는 API가 있다는 사실에 놀랐습니다.

공공 API는 누구나 무료로 사용할 수 있는 API입니다. 날씨, 환율, 도서 정보, 영화 정보 등 다양한 데이터를 제공합니다.

회원가입만 하면 API 키를 받을 수 있고, 실제 서비스처럼 데이터를 주고받을 수 있습니다. 포트폴리오나 학습용 프로젝트에 활용하기 좋습니다.

다음 코드를 살펴봅시다.

import requests

# 1. JSONPlaceholder - 가짜 REST API (연습용)
response = requests.get("https://jsonplaceholder.typicode.com/posts/1")
post = response.json()
print(f"게시글 제목: {post['title']}")

# 2. Open Weather Map - 날씨 정보 (API 키 필요)
api_key = "your_api_key"
city = "Seoul"
weather_url = f"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={api_key}&units=metric"
response = requests.get(weather_url)
weather = response.json()
print(f"서울 온도: {weather['main']['temp']}도")

# 3. 공공데이터포털 - 한국 정부 데이터
# 예: 전국 도서관 정보, 대기오염 정보 등
# https://www.data.go.kr 에서 API 신청

김개발 씨는 날씨 앱을 만들고 싶었습니다. 하지만 날씨 데이터를 어디서 구하지?

직접 기상청에 연락해야 하나? 비용이 얼마나 들까?

고민이 많았습니다. 박시니어 씨가 웃으며 말했습니다.

"OpenWeatherMap 같은 무료 API가 많아요. 회원가입하고 API 키 받으면 끝이에요." 그렇다면 무료 공공 API에는 어떤 것들이 있을까요?

공공 API를 이해하는 좋은 비유는 공공 도서관입니다. 도서관은 누구나 무료로 책을 빌릴 수 있습니다.

다만 회원증을 만들어야 하고, 한 번에 빌릴 수 있는 권수에 제한이 있습니다. 공공 API도 똑같습니다.

무료지만 API 키를 받아야 하고, 하루에 호출할 수 있는 횟수에 제한이 있습니다. 공공 API가 등장하기 전에는 어땠을까요?

개발자들은 데이터를 직접 수집해야 했습니다. 날씨 정보가 필요하면 기상청 사이트를 크롤링하거나, 직접 계약을 맺어야 했습니다.

영화 정보가 필요하면 영화관 사이트를 일일이 파싱해야 했습니다. 시간도 오래 걸리고 법적 문제가 생길 수도 있었습니다.

더 큰 문제는 초보 개발자의 학습이었습니다. 실제 데이터 없이 API 개발을 배우기 어려웠습니다.

가짜 데이터를 직접 만들어야 했는데, 이것도 쉽지 않았습니다. 바로 이런 문제를 해결하기 위해 무료 공공 API가 많이 등장했습니다.

가장 유명한 것이 JSONPlaceholder입니다. 이것은 연습용 가짜 REST API입니다.

게시글, 댓글, 사용자 데이터를 제공합니다. 회원가입도 필요 없고, 무제한으로 사용할 수 있습니다.

API 개발을 처음 배울 때 최고의 선택입니다. 실제 데이터가 필요하면 OpenWeatherMap을 추천합니다.

전 세계 20만 개 도시의 날씨 정보를 제공합니다. 무료 플랜은 하루 1000번 호출할 수 있습니다.

개인 프로젝트에는 충분한 양입니다. 회원가입 후 API 키를 받으면 바로 사용할 수 있습니다.

한국 데이터가 필요하면 공공데이터포털을 확인하세요. 정부에서 운영하는 사이트로, 전국 도서관 정보, 대기오염 정보, 지하철 실시간 도착 정보 등 수천 개의 API를 제공합니다.

회원가입 후 API를 신청하면 승인까지 1-2일 걸립니다. 위의 코드를 한 줄씩 살펴보겠습니다.

JSONPlaceholder는 API 키가 필요 없습니다. 바로 URL로 요청하면 응답이 옵니다.

게시글, 댓글, 사용자 등 다양한 엔드포인트를 제공합니다. 연습하기에 완벽합니다.

OpenWeatherMap은 API 키가 필요합니다. 사이트에서 회원가입 후 대시보드에서 API 키를 복사하면 됩니다.

URL에 appid 파라미터로 API 키를 전달합니다. units=metric은 섭씨 온도를 사용하겠다는 의미입니다.

공공데이터포털은 각 API마다 사용법이 다릅니다. 문서를 참고해서 필요한 파라미터를 전달해야 합니다.

실제 현업에서는 어떻게 활용할까요? 많은 스타트업이 초기에는 공공 API를 활용합니다.

날씨 기반 추천 서비스를 만든다면 OpenWeatherMap으로 시작합니다. 서비스가 성장하면 유료 플랜으로 전환하거나, 더 전문적인 기상 데이터 API로 바꿉니다.

이렇게 빠르게 프로토타입을 만들고 검증할 수 있습니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수는 무료 API의 제한을 무시하는 것입니다. 하루 1000번 호출 제한이 있는데, 무한 루프를 돌려서 순식간에 제한에 걸리는 경우가 많습니다.

또한 무료 API는 갑자기 서비스가 중단될 수도 있습니다. 실제 서비스에 사용하려면 유료 플랜을 고려하거나, 대안 API를 미리 찾아두어야 합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 OpenWeatherMap으로 날씨 앱을 완성했습니다.

포트폴리오에 올리니 면접에서 좋은 반응을 받았습니다. 무료 공공 API를 활용하면 실제 데이터로 프로젝트를 만들 수 있습니다.

학습용으로도, 포트폴리오용으로도 훌륭합니다. 여러분도 오늘 배운 API들을 활용해서 멋진 프로젝트를 만들어보세요.

실전 팁

💡 - 무료 API는 호출 제한이 있으니 캐싱을 활용하세요

API 키는 환경변수로 관리해서 GitHub에 올라가지 않게 주의하세요
더 많은 무료 API는 "public-apis" GitHub 저장소에서 찾을 수 있습니다

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

#Python#API#REST#JSON#HTTP

API 개념과 JSON 데이터 완벽 가이드

초급 개발자를 위한 API와 JSON 데이터 기초부터 실전 활용까지. REST API 개념, HTTP 메서드, JSON 데이터 구조를 실무 스토리로 쉽게 배웁니다.

# API 개념과 JSON 데이터 완벽 가이드 초급 개발자를 위한 API와 JSON 데이터 기초부터 실전 활용까지. REST API 개념, HTTP 메서드, JSON 데이터 구조를 실무 스토리로 쉽게 배웁니다. --- ## 목차 1. [API란 무엇인가?](#api란-무엇인가?) 2. [REST API 개념 이해](#rest-api-개념-이해) 3. [HTTP 메서드 (GET, POST)](#http-메서드-(get,-post)) 4. [JSON 데이터 구조](#json-데이터-구조) 5. [JSON vs CSV 비교](#json-vs-csv-비교) 6. [API 문서 읽는 법](#api-문서-읽는-법) 7. [무료 공공 API 소개](#무료-공공-api-소개) --- ## 1. API란 무엇인가? 신입 개발자 김개발 씨는 오늘도 회의실에서 선배들의 대화를 듣고 있었습니다. "이 기능은 외부 API 연동하면 금방이에요." 김개발 씨는 고개를 끄덕였지만, 사실 API가 정확히 무엇인지 잘 몰랐습니다. 회의가 끝나고 책상으로 돌아온 김개발 씨는 검색창에 "API란 무엇인가"를 입력했습니다. **API**(Application Programming Interface)는 프로그램끼리 소통하는 약속된 방법입니다. 마치 식당에서 메뉴판을 보고 주문하는 것처럼, API는 프로그램이 다른 프로그램에게 "이런 작업을 해주세요"라고 요청할 수 있게 해줍니다. 복잡한 내부 구조를 몰라도 정해진 방법으로 원하는 기능을 사용할 수 있습니다. 다음 코드를 살펴봅시다. ```python import requests # 날씨 API에 요청을 보냅니다 url = "https://api.weatherapi.com/v1/current.json" params = { "key": "your_api_key", "q": "Seoul" } # API 호출 response = requests.get(url, params=params) # 응답 받기 weather_data = response.json() print(f"서울 날씨: {weather_data['current']['temp_c']}도") ``` 김개발 씨는 입사 2주 차 신입 개발자입니다. 오늘 팀장님께서 "날씨 정보를 보여주는 기능을 추가해보세요"라는 업무를 주셨습니다. 김개발 씨는 당황했습니다. 날씨 데이터를 어떻게 구하지? 옆자리 선배 박시니어 씨가 말했습니다. "날씨 API 쓰면 돼요. 간단해요." 그렇다면 API란 정확히 무엇일까요? **API**를 이해하는 가장 쉬운 방법은 식당의 메뉴판과 종업원을 떠올리는 것입니다. 손님인 여러분은 주방이 어떻게 생겼는지, 요리사가 어떤 방법으로 요리하는지 알 필요가 없습니다. 그저 메뉴판을 보고 "김치찌개 하나요"라고 주문하면 됩니다. 종업원이 주문을 받아 주방에 전달하고, 완성된 요리를 가져다줍니다. API도 이와 똑같습니다. 여러분의 프로그램은 손님이고, 다른 회사의 서비스는 주방입니다. API는 메뉴판이자 종업원 역할을 합니다. API가 없던 시절에는 어땠을까요? 모든 기능을 직접 만들어야 했습니다. 날씨 정보가 필요하면 기상청 데이터베이스에 직접 접근해서 복잡한 처리를 거쳐야 했습니다. 지도 기능이 필요하면 지도 데이터를 직접 수집하고 렌더링 엔진을 개발해야 했습니다. 이런 작업은 수개월에서 수년이 걸렸습니다. 더 큰 문제는 보안과 유지보수였습니다. 다른 회사의 시스템에 직접 접근하려면 복잡한 권한 설정이 필요했고, 데이터 구조가 바뀔 때마다 코드를 전부 수정해야 했습니다. 바로 이런 문제를 해결하기 위해 **API**가 등장했습니다. API를 사용하면 복잡한 내부 구조를 몰라도 됩니다. 정해진 주소(URL)로 요청을 보내고, 약속된 형식으로 응답을 받으면 끝입니다. 또한 보안도 간단해집니다. API 키라는 일종의 출입증만 받으면 안전하게 데이터를 주고받을 수 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 `requests` 라이브러리를 불러옵니다. 이것은 Python에서 API 요청을 보낼 때 가장 많이 사용하는 도구입니다. 다음으로 API 주소(url)를 설정합니다. 이것이 바로 "어디에 요청을 보낼지"를 정하는 부분입니다. 그리고 `params`에 필요한 정보를 담습니다. API 키와 도시 이름을 전달합니다. `requests.get()`으로 실제 요청을 보내고, `response.json()`으로 응답을 받아옵니다. 실제 현업에서는 어떻게 활용할까요? 쇼핑몰 서비스를 개발한다고 가정해봅시다. 결제 기능이 필요하면 토스페이먼츠 API를 사용하고, 배송 조회가 필요하면 택배사 API를 연동하고, 상품 추천이 필요하면 AI 추천 API를 사용합니다. 각 기능을 직접 개발하는 대신 API로 연결하면 몇 시간 만에 완성할 수 있습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 API 키를 코드에 그대로 적어두는 것입니다. API 키는 출입증과 같아서 다른 사람이 알게 되면 여러분의 계정으로 무단 사용될 수 있습니다. 따라서 환경변수나 별도 설정 파일에 보관해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다. "아, API는 다른 프로그램의 기능을 빌려 쓰는 거군요!" API를 제대로 이해하면 개발 속도가 비약적으로 빨라집니다. 필요한 기능을 직접 만드는 대신 검증된 API를 활용하세요. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - API 키는 절대 코드에 직접 쓰지 말고 환경변수로 관리하세요 - 무료 API는 호출 횟수 제한이 있으니 문서를 꼭 확인하세요 - API 응답은 항상 예외 처리를 해두어야 안전합니다 --- ## 2. REST API 개념 이해 김개발 씨는 API 문서를 읽다가 "RESTful API"라는 단어를 발견했습니다. API는 알겠는데, REST는 또 뭘까요? 박시니어 씨에게 물어보니 "요즘 API는 대부분 REST 방식이에요"라고 답했습니다. 김개발 씨는 REST API가 무엇인지 제대로 알아보기로 했습니다. **REST API**는 웹의 장점을 최대한 활용하는 API 설계 방식입니다. 마치 도서관에서 책을 분류하듯이, 자원(데이터)을 URL로 표현하고 HTTP 메서드로 동작을 정의합니다. GET으로 조회하고, POST로 생성하고, PUT으로 수정하고, DELETE로 삭제하는 직관적인 구조입니다. 다음 코드를 살펴봅시다. ```python import requests # REST API 기본 구조 base_url = "https://api.example.com" # 사용자 목록 조회 (GET) response = requests.get(f"{base_url}/users") users = response.json() # 특정 사용자 조회 (GET) user_id = 123 response = requests.get(f"{base_url}/users/{user_id}") user = response.json() # 새 사용자 생성 (POST) new_user = {"name": "김개발", "email": "kim@example.com"} response = requests.post(f"{base_url}/users", json=new_user) ``` 김개발 씨는 회사에서 사용자 관리 API를 만드는 업무를 받았습니다. 선배에게 참고할 만한 코드를 부탁하니 "REST 원칙을 따라서 만들어보세요"라는 답변이 돌아왔습니다. 김개발 씨는 당황했습니다. 그날 저녁, 김개발 씨는 REST API에 대해 공부하기 시작했습니다. **REST**를 이해하는 가장 좋은 비유는 도서관입니다. 도서관에서 책을 찾을 때를 생각해보세요. "문학 -> 한국 소설 -> ㄱ -> 김유정"처럼 계층적으로 위치를 표현합니다. 그리고 "책 빌리기", "책 반납하기", "책 예약하기"처럼 동작도 명확하게 구분됩니다. REST API도 똑같습니다. 자원의 위치를 URL로 표현하고, 동작을 HTTP 메서드로 구분합니다. REST가 등장하기 전에는 어땠을까요? 각 회사마다 API를 제멋대로 만들었습니다. 어떤 회사는 `/getUserList`라는 주소를 사용하고, 다른 회사는 `/getUsers`를 사용했습니다. 같은 기능인데도 회사마다 이름과 방식이 달라서 개발자들은 매번 새로운 API를 배워야 했습니다. 더 큰 문제는 일관성 부족이었습니다. 사용자를 조회할 때는 GET을 쓰다가, 삭제할 때는 POST를 쓰는 식으로 혼란스러웠습니다. API 문서를 하나하나 읽어봐야만 사용법을 알 수 있었습니다. 바로 이런 혼란을 정리하기 위해 **REST** 원칙이 등장했습니다. REST를 따르면 API가 직관적이 됩니다. `/users`는 사용자 목록을, `/users/123`은 123번 사용자를 의미한다는 것을 누구나 알 수 있습니다. 또한 HTTP 메서드만 보면 무슨 동작인지 알 수 있습니다. GET은 조회, POST는 생성, PUT은 수정, DELETE는 삭제입니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 기본 URL을 설정합니다. 이것은 API 서버의 주소입니다. `/users`로 요청을 보내면 모든 사용자 목록을 받아옵니다. 이것이 **컬렉션**(collection) 개념입니다. `/users/123`처럼 특정 ID를 붙이면 개별 사용자 정보를 받아옵니다. 이것이 **리소스**(resource) 개념입니다. 새 사용자를 만들 때는 POST 메서드를 사용합니다. 데이터를 `json` 파라미터로 전달하면 서버가 새 사용자를 생성합니다. 실제 현업에서는 어떻게 활용할까요? 블로그 서비스를 만든다고 가정해봅시다. 게시글은 `/posts`로, 댓글은 `/posts/123/comments`로 표현합니다. 계층 구조가 명확하죠. 사용자가 게시글을 작성하면 POST, 수정하면 PUT, 삭제하면 DELETE를 사용합니다. 이렇게 REST 원칙을 따르면 API 문서가 없어도 대략적인 사용법을 짐작할 수 있습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수는 URL에 동사를 넣는 것입니다. `/getUsers`, `/createUser`처럼 말이죠. REST에서는 URL은 자원만 표현하고, 동작은 HTTP 메서드로 표현해야 합니다. 올바른 방식은 `GET /users`, `POST /users`입니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 다음 날 김개발 씨는 REST 원칙을 따라 API를 설계했습니다. 박시니어 씨가 코드 리뷰를 하더니 엄지를 들어 올렸습니다. "완벽해요!" REST API를 제대로 이해하면 누구나 이해하기 쉬운 API를 만들 수 있습니다. 일관된 규칙을 따르면 유지보수도 훨씬 쉬워집니다. 여러분도 오늘 배운 REST 원칙을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - URL에는 명사만, 동작은 HTTP 메서드로 표현하세요 - 계층 구조는 `/` 로 명확하게 나타내세요 - 버전 관리는 `/v1/users` 처럼 URL에 명시하는 것이 좋습니다 --- ## 3. HTTP 메서드 (GET, POST) 김개발 씨는 API 개발을 하다가 궁금한 점이 생겼습니다. GET과 POST는 언제 쓰는 걸까요? 둘 다 데이터를 주고받는 건데 뭐가 다른 걸까요? 박시니어 씨에게 물어보니 "GET은 조회할 때, POST는 생성할 때 쓴다"고 간단히 설명해주었습니다. 하지만 김개발 씨는 더 깊이 알고 싶었습니다. **HTTP 메서드**는 서버에게 "무엇을 할지" 알려주는 동사입니다. **GET**은 데이터를 가져올 때, **POST**는 새로운 데이터를 만들 때 사용합니다. GET은 URL에 데이터가 보이지만 POST는 본문에 숨겨서 보냅니다. 또한 GET은 여러 번 호출해도 결과가 같지만, POST는 호출할 때마다 새로운 데이터가 생성됩니다. 다음 코드를 살펴봅시다. ```python import requests # GET 요청 - 데이터 조회 # URL에 파라미터가 노출됩니다 params = {"page": 1, "size": 10} response = requests.get("https://api.example.com/posts", params=params) posts = response.json() print(f"게시글 {len(posts)}개 조회됨") # POST 요청 - 데이터 생성 # 데이터가 본문에 담겨서 전송됩니다 new_post = { "title": "API 공부 시작", "content": "오늘부터 API를 배웁니다", "author": "김개발" } response = requests.post("https://api.example.com/posts", json=new_post) created = response.json() print(f"게시글 ID {created['id']} 생성됨") ``` 김개발 씨는 게시판 기능을 만들고 있었습니다. 게시글 목록을 보여주고, 새 게시글을 작성하는 기능이 필요했습니다. 두 기능 모두 서버와 통신해야 하는데, 어떤 메서드를 써야 할지 고민이 되었습니다. 박시니어 씨가 지나가다 말했습니다. "목록 보기는 GET, 글 작성은 POST죠." 그렇다면 GET과 POST는 정확히 무엇이 다를까요? **HTTP 메서드**를 이해하는 좋은 비유는 도서관의 행동입니다. 도서관에서 책을 찾아보는 것은 **GET**입니다. 책장을 아무리 뒤져도 책이 없어지거나 바뀌지 않습니다. 반면 대출 신청서를 작성하는 것은 **POST**입니다. 신청서를 낼 때마다 새로운 대출 기록이 생깁니다. GET과 POST를 구분하지 않던 시절에는 어땠을까요? 모든 요청을 POST로 처리하는 사이트들이 많았습니다. 게시글을 조회하는데도 POST를 쓰고, 검색하는데도 POST를 썼습니다. 이렇게 되면 브라우저의 뒤로가기 버튼을 눌렀을 때 "양식을 다시 제출하시겠습니까?"라는 경고창이 뜹니다. 사용자는 불안해집니다. 더 큰 문제는 캐싱입니다. GET 요청은 브라우저가 결과를 저장해두었다가 재사용할 수 있습니다. 하지만 POST는 매번 서버에 새로 요청해야 합니다. 성능 차이가 크게 납니다. 바로 이런 이유로 **GET**과 **POST**를 명확히 구분해야 합니다. GET을 사용하면 URL만 봐도 어떤 데이터를 요청하는지 알 수 있습니다. 브라우저 주소창에 `?page=1&size=10`처럼 표시되기 때문입니다. 또한 URL을 복사해서 공유할 수 있습니다. 친구에게 "이 링크 봐봐"라고 보낼 수 있죠. 반면 POST는 데이터가 본문에 담겨서 전송됩니다. URL에는 보이지 않습니다. 로그인할 때 비밀번호가 주소창에 보이면 안 되겠죠? 또한 POST는 호출할 때마다 서버의 상태가 바뀝니다. 게시글을 작성하면 데이터베이스에 새 레코드가 추가됩니다. 위의 코드를 한 줄씩 살펴보겠습니다. GET 요청에서는 `params` 딕셔너리로 파라미터를 전달합니다. requests 라이브러리가 자동으로 URL에 `?page=1&size=10`을 붙여줍니다. 서버는 1페이지의 10개 게시글을 반환합니다. POST 요청에서는 `json` 파라미터로 데이터를 전달합니다. 이 데이터는 요청 본문에 JSON 형식으로 담깁니다. 서버는 새 게시글을 생성하고, 생성된 게시글의 ID를 반환합니다. 실제 현업에서는 어떻게 활용할까요? 쇼핑몰 서비스를 생각해봅시다. 상품 목록을 보여줄 때는 GET을 사용합니다. 사용자가 "파란색 신발"을 검색하면 URL이 `/products?color=blue&category=shoes`가 됩니다. 이 URL을 친구에게 공유할 수 있습니다. 반면 장바구니에 상품을 담을 때는 POST를 사용합니다. 버튼을 누를 때마다 장바구니에 항목이 추가되어야 하니까요. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수는 GET으로 데이터를 변경하려는 것입니다. 예를 들어 `/deleteUser?id=123` 같은 URL을 만드는 경우입니다. 이렇게 하면 누군가 이 링크를 클릭하거나, 검색 엔진이 크롤링하면 데이터가 삭제될 수 있습니다. 위험합니다. 데이터를 변경하는 작업은 반드시 POST나 DELETE를 써야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 게시판 기능을 완성했습니다. 목록 조회는 GET, 글 작성은 POST로 구현했습니다. 테스트해보니 완벽하게 작동했습니다. GET과 POST를 올바르게 사용하면 안전하고 효율적인 API를 만들 수 있습니다. 각 메서드의 특성을 이해하고 적재적소에 활용하세요. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - 데이터 조회는 GET, 생성/수정/삭제는 POST/PUT/DELETE를 사용하세요 - GET 요청에는 민감한 정보를 담지 마세요 - POST 요청 후에는 적절한 상태 코드(201 Created)를 반환하세요 --- ## 4. JSON 데이터 구조 김개발 씨는 API 응답을 받고 나서 당황했습니다. 화면에 뭔가 이상한 텍스트가 출력되었습니다. 중괄호와 대괄호가 가득한 문자열이었습니다. 박시니어 씨가 웃으며 말했습니다. "그게 JSON이에요. API는 대부분 JSON으로 데이터를 주고받아요." 김개발 씨는 JSON이 무엇인지 알아보기로 했습니다. **JSON**(JavaScript Object Notation)은 데이터를 주고받을 때 사용하는 텍스트 형식입니다. 마치 엑셀 표를 텍스트로 표현한 것처럼, 구조화된 데이터를 중괄호와 대괄호로 나타냅니다. 사람이 읽기 쉽고, 프로그램이 처리하기도 쉬워서 API의 표준 형식이 되었습니다. 다음 코드를 살펴봅시다. ```python import json # JSON 문자열 (API에서 받은 응답) json_string = ''' { "user": { "id": 123, "name": "김개발", "email": "kim@example.com", "skills": ["Python", "JavaScript", "API"], "is_active": true } } ''' # JSON을 Python 딕셔너리로 변환 data = json.loads(json_string) print(f"사용자 이름: {data['user']['name']}") print(f"보유 스킬: {', '.join(data['user']['skills'])}") # Python 객체를 JSON 문자열로 변환 new_user = {"id": 456, "name": "박시니어", "level": 5} json_output = json.dumps(new_user, ensure_ascii=False, indent=2) print(json_output) ``` 김개발 씨는 사용자 정보를 가져오는 API를 호출했습니다. 응답이 왔지만 형식이 낯설었습니다. 중괄호 안에 이름, 이메일, 스킬 목록이 담겨 있었습니다. "이걸 어떻게 사용하지?" 박시니어 씨가 설명했습니다. "JSON은 데이터 형식이에요. Python 딕셔너리랑 비슷해요." 그렇다면 **JSON**은 정확히 무엇일까요? JSON을 이해하는 가장 좋은 비유는 택배 송장입니다. 택배를 보낼 때 "보내는 사람: 김개발, 받는 사람: 박시니어, 주소: 서울시..."처럼 정보를 구조화해서 적습니다. JSON도 똑같습니다. 데이터를 "이름: 값" 형식으로 정리해서 전달합니다. JSON이 등장하기 전에는 어땠을까요? **XML**이라는 복잡한 형식을 사용했습니다. XML은 태그가 많아서 같은 데이터를 표현해도 용량이 2-3배 컸습니다. 또한 사람이 읽기 어려웠습니다. 태그의 시작과 끝을 일일이 확인해야 했으니까요. 더 큰 문제는 파싱(해석)이 복잡했다는 것입니다. XML을 읽으려면 특별한 라이브러리가 필요했고, 코드도 길어졌습니다. 단순히 사용자 이름을 가져오는데도 여러 줄의 코드가 필요했습니다. 바로 이런 불편함을 해결하기 위해 **JSON**이 등장했습니다. JSON은 JavaScript 객체 표기법에서 유래했지만, 지금은 모든 프로그래밍 언어에서 지원합니다. Python에서는 딕셔너리와 리스트로 자연스럽게 변환됩니다. 중괄호는 딕셔너리, 대괄호는 리스트를 의미합니다. 또한 JSON은 타입을 명확히 구분합니다. 문자열은 큰따옴표로 감싸고, 숫자는 그대로 쓰고, 불린은 true/false로 표현합니다. null도 지원합니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 API에서 받은 JSON 문자열이 있습니다. 이것은 그냥 텍스트입니다. `json.loads()` 함수로 이 텍스트를 Python 딕셔너리로 변환합니다. 그러면 `data['user']['name']`처럼 접근할 수 있습니다. 반대로 Python 객체를 JSON 문자열로 만들 때는 `json.dumps()`를 사용합니다. `ensure_ascii=False`는 한글이 깨지지 않게 하는 옵션이고, `indent=2`는 보기 좋게 들여쓰기를 추가하는 옵션입니다. 실제 현업에서는 어떻게 활용할까요? 웹 서비스를 만들 때 프론트엔드와 백엔드는 JSON으로 대화합니다. 사용자가 회원가입 폼을 작성하면 프론트엔드가 입력값을 JSON으로 만들어 서버에 보냅니다. 서버는 처리 결과를 JSON으로 응답합니다. 모바일 앱도 마찬가지입니다. JSON은 사실상 웹 통신의 표준 언어가 되었습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수는 JSON 형식을 잘못 만드는 것입니다. 큰따옴표 대신 작은따옴표를 쓰거나, 마지막 항목 뒤에 쉼표를 붙이면 에러가 납니다. JSON은 형식이 엄격합니다. 또한 딕셔너리의 키는 반드시 문자열이어야 합니다. 숫자나 불린은 키가 될 수 없습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 JSON을 딕셔너리로 변환하는 방법을 배웠습니다. 이제 API 응답을 자유자재로 다룰 수 있게 되었습니다. JSON을 제대로 이해하면 API 개발과 데이터 처리가 훨씬 수월해집니다. 대부분의 현대 API가 JSON을 사용하니 필수로 알아야 하는 지식입니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - JSON 형식이 올바른지 확인하려면 jsonlint.com 같은 검증 도구를 사용하세요 - 큰 JSON 데이터는 indent 옵션으로 보기 좋게 출력하세요 - JSON은 주석을 지원하지 않으니 설명이 필요하면 별도 문서를 작성하세요 --- ## 5. JSON vs CSV 비교 김개발 씨는 데이터를 파일로 저장해야 하는 업무를 받았습니다. 박시니어 씨가 물었습니다. "JSON으로 저장할래요, CSV로 저장할래요?" 김개발 씨는 두 형식의 차이를 몰랐습니다. 언제 JSON을 쓰고 언제 CSV를 써야 하는 걸까요? **JSON**은 계층 구조가 있는 복잡한 데이터에 적합하고, **CSV**는 표 형태의 단순한 데이터에 적합합니다. JSON은 중첩된 객체와 배열을 표현할 수 있지만, CSV는 행과 열로만 데이터를 표현합니다. JSON은 API 통신에, CSV는 엑셀 데이터 교환에 주로 사용됩니다. 다음 코드를 살펴봅시다. ```python import json import csv # 같은 데이터를 JSON과 CSV로 표현 # JSON 형식 - 계층 구조 표현 가능 users_json = [ { "id": 1, "name": "김개발", "skills": ["Python", "API"], # 배열 가능 "address": { # 중첩 객체 가능 "city": "서울", "district": "강남구" } } ] with open("users.json", "w", encoding="utf-8") as f: json.dump(users_json, f, ensure_ascii=False, indent=2) # CSV 형식 - 평면 구조만 가능 users_csv = [ ["id", "name", "skills", "city", "district"], [1, "김개발", "Python;API", "서울", "강남구"] # 배열은 문자열로 변환 ] with open("users.csv", "w", encoding="utf-8", newline="") as f: writer = csv.writer(f) writer.writerows(users_csv) ``` 김개발 씨는 사용자 데이터 100명분을 파일로 저장해야 했습니다. 각 사용자는 이름, 이메일, 보유 스킬, 주소 정보를 가지고 있었습니다. 어떤 형식으로 저장해야 할까요? 박시니어 씨가 조언했습니다. "데이터 구조를 보고 결정하세요." 그렇다면 JSON과 CSV는 각각 언제 사용해야 할까요? 두 형식을 비교하는 좋은 비유는 책과 표입니다. 소설책은 챕터 안에 섹션이 있고, 섹션 안에 문단이 있는 **계층 구조**입니다. 이것이 JSON입니다. 반면 시간표는 행과 열로 이루어진 **평면 구조**입니다. 이것이 CSV입니다. 두 형식이 공존하게 된 이유는 무엇일까요? 초기에는 CSV가 주로 쓰였습니다. 데이터베이스 테이블을 그대로 텍스트로 옮기기 좋았으니까요. 엑셀에서 열고 수정하기도 쉬웠습니다. 하지만 웹 서비스가 발전하면서 데이터가 복잡해졌습니다. 사용자 한 명이 여러 개의 스킬을 가지고, 주소도 시/구/동으로 나뉘는 식으로요. CSV로는 이런 계층 구조를 표현하기 어려웠습니다. 배열을 세미콜론으로 구분하거나, 주소를 한 칸에 몰아 넣어야 했습니다. 데이터를 다시 읽을 때 파싱이 복잡해졌습니다. 바로 이런 문제를 해결하기 위해 **JSON**이 선호되기 시작했습니다. JSON은 중첩된 객체를 자연스럽게 표현합니다. 사용자의 주소가 `address` 객체 안에 `city`와 `district`를 가지는 식으로 말이죠. 스킬 목록도 진짜 배열로 저장할 수 있습니다. 데이터를 읽을 때도 `user['address']['city']`처럼 직관적으로 접근할 수 있습니다. 반면 CSV의 장점은 단순함입니다. 엑셀이나 구글 시트에서 바로 열 수 있습니다. 비개발자도 쉽게 데이터를 확인하고 수정할 수 있습니다. 또한 용량이 작습니다. 같은 데이터를 JSON으로 저장하면 중괄호와 키 이름 때문에 용량이 커집니다. 위의 코드를 한 줄씩 살펴보겠습니다. JSON으로 저장할 때는 `json.dump()`를 사용합니다. Python 리스트와 딕셔너리를 그대로 전달하면 자동으로 JSON 형식으로 변환됩니다. 계층 구조가 그대로 유지됩니다. CSV로 저장할 때는 `csv.writer()`를 사용합니다. 첫 번째 행은 헤더(컬럼 이름)입니다. 그다음 행부터 데이터를 씁니다. 배열인 스킬은 세미콜론으로 연결해서 하나의 문자열로 만들어야 합니다. 중첩 객체인 주소는 평면화해서 각 필드를 별도 컬럼으로 분리합니다. 실제 현업에서는 어떻게 선택할까요? API 응답은 거의 항상 JSON입니다. 웹과 모바일 앱이 서버와 통신할 때는 JSON이 표준입니다. 설정 파일도 JSON이 많이 쓰입니다. 반면 데이터 분석 팀과 협업할 때는 CSV를 많이 사용합니다. 분석가들은 엑셀이나 파이썬 pandas로 CSV를 쉽게 다룰 수 있으니까요. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수는 복잡한 데이터를 억지로 CSV에 우겨 넣는 것입니다. 배열을 세미콜론으로 구분하고, 중첩 객체를 JSON 문자열로 변환해서 한 칸에 넣는 식으로요. 이렇게 하면 나중에 읽을 때 파싱이 복잡해지고 버그가 생기기 쉽습니다. 복잡한 구조는 처음부터 JSON을 쓰는 것이 좋습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 데이터 구조를 살펴보고 JSON을 선택했습니다. 사용자마다 보유 스킬 개수가 달랐고, 주소 정보도 계층 구조였기 때문입니다. JSON과 CSV의 특성을 이해하면 상황에 맞는 형식을 선택할 수 있습니다. 복잡한 구조는 JSON, 단순한 표는 CSV로 저장하세요. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - 데이터 구조가 복잡하면 JSON, 단순하면 CSV를 선택하세요 - 비개발자와 협업할 때는 CSV가 편리합니다 - CSV는 쉼표가 데이터에 포함되면 문제가 생기니 주의하세요 --- ## 6. API 문서 읽는 법 김개발 씨는 회사에서 새로운 결제 API를 연동하는 업무를 받았습니다. API 문서를 열어보니 수십 페이지에 달하는 영어 설명이 나왔습니다. 어디서부터 읽어야 할지 막막했습니다. 박시니어 씨가 조언했습니다. "API 문서는 읽는 순서가 있어요." **API 문서**는 API 사용 설명서입니다. 기본 URL, 인증 방법, 엔드포인트 목록, 요청/응답 예시로 구성됩니다. 처음에는 **인증 섹션**과 **빠른 시작 가이드**를 먼저 읽고, 필요한 엔드포인트만 찾아서 읽는 것이 효율적입니다. 모든 페이지를 읽으려 하지 마세요. 다음 코드를 살펴봅시다. ```python import requests # API 문서에서 찾아야 할 정보들 # 1. 기본 URL (Base URL) base_url = "https://api.example.com/v1" # 2. 인증 방법 (API Key, Bearer Token 등) headers = { "Authorization": "Bearer your_api_key_here", "Content-Type": "application/json" } # 3. 엔드포인트와 메서드 # 문서: GET /users/{id} - 특정 사용자 조회 user_id = 123 response = requests.get(f"{base_url}/users/{user_id}", headers=headers) # 4. 응답 형식 확인 if response.status_code == 200: user = response.json() print(f"이름: {user['name']}") else: # 5. 에러 코드 처리 print(f"에러 {response.status_code}: {response.text}") ``` 김개발 씨는 토스페이먼츠 API 문서를 펼쳐 놓았습니다. 목차만 봐도 수십 개 항목이 있었습니다. "이걸 다 읽어야 하나?" 김개발 씨는 막막했습니다. 박시니어 씨가 모니터를 보며 말했습니다. "문서 전체를 읽을 필요는 없어요. 필요한 부분만 찾아 읽으면 돼요." 그렇다면 **API 문서**를 효율적으로 읽는 방법은 무엇일까요? API 문서를 읽는 것은 마치 여행 가이드북을 읽는 것과 같습니다. 파리 여행을 간다고 가이드북을 첫 페이지부터 끝까지 읽지는 않죠. 지도를 보고 교통 정보를 확인한 다음, 가고 싶은 장소만 찾아서 읽습니다. API 문서도 똑같습니다. API 문서가 잘 정리되지 않았던 시절에는 어땠을까요? 개발자들은 서버 개발자에게 직접 물어봐야 했습니다. "이 API 어떻게 호출해요?", "에러 코드 400은 무슨 뜻이에요?" 같은 질문을 반복했습니다. 커뮤니케이션 비용이 컸고, 서버 개발자는 계속 같은 질문에 답해야 했습니다. 더 큰 문제는 외부 API를 사용할 때였습니다. 문서가 없으면 시행착오로 API를 탐색해야 했습니다. 어떤 파라미터를 보내야 하는지, 응답이 어떤 형식인지 하나하나 테스트해봐야 했습니다. 바로 이런 비효율을 없애기 위해 **잘 작성된 API 문서**가 중요해졌습니다. 좋은 API 문서는 일정한 구조를 따릅니다. 첫째, **개요** 섹션에서 API가 무엇을 하는지 설명합니다. 둘째, **인증** 섹션에서 API 키를 받는 방법과 요청에 포함하는 방법을 알려줍니다. 셋째, **빠른 시작** 가이드에서 5분 안에 첫 API 호출을 성공시킬 수 있게 도와줍니다. 그다음 **엔드포인트 레퍼런스**가 나옵니다. 이것이 문서의 대부분을 차지합니다. 하지만 처음부터 끝까지 읽을 필요는 없습니다. 필요한 기능의 엔드포인트만 찾아서 읽으면 됩니다. 각 엔드포인트 문서는 보통 이런 정보를 담고 있습니다. HTTP 메서드와 URL 경로, 필수/선택 파라미터 목록, 요청 예시, 성공 응답 예시, 에러 응답 예시가 그것입니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 문서에서 **기본 URL**을 찾아야 합니다. 보통 문서 첫 페이지나 인증 섹션에 나와 있습니다. 다음으로 **인증 방법**을 확인합니다. API 키를 헤더에 넣는지, 파라미터로 보내는지 확인해야 합니다. 이 예제에서는 Bearer Token 방식입니다. 그다음 필요한 **엔드포인트**를 찾습니다. 사용자 정보를 가져오고 싶다면 "사용자 조회" 엔드포인트를 찾으면 됩니다. 문서에 `GET /users/{id}`라고 나와 있으면, `{id}` 부분을 실제 숫자로 바꿔서 요청하면 됩니다. 마지막으로 **에러 처리**를 확인합니다. 상태 코드가 200이 아니면 뭔가 문제가 있는 것입니다. 문서의 에러 코드 섹션을 보면 각 코드의 의미를 알 수 있습니다. 실제 현업에서는 어떻게 활용할까요? 새로운 API를 연동할 때 개발자들은 이런 순서로 작업합니다. 첫째, 빠른 시작 가이드를 따라 첫 호출에 성공합니다. 둘째, 필요한 기능의 엔드포인트 3-4개를 찾아서 자세히 읽습니다. 셋째, Postman 같은 도구로 실제 요청을 보내보고 응답을 확인합니다. 넷째, 코드로 구현합니다. 문서를 다 읽고 나서 코딩을 시작하는 것이 아니라, 필요한 부분만 읽으면서 동시에 개발을 진행합니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수는 문서를 대충 읽고 바로 코딩부터 하는 것입니다. 특히 인증 부분을 제대로 읽지 않아서 401 Unauthorized 에러를 계속 받는 경우가 많습니다. 또한 요청 예시는 보지만 응답 예시는 안 보는 실수도 많습니다. 응답 구조를 모르면 데이터를 제대로 파싱할 수 없습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언대로 김개발 씨는 인증 섹션과 결제 생성 엔드포인트만 집중해서 읽었습니다. 30분 만에 첫 결제 API 호출에 성공했습니다. API 문서를 효율적으로 읽는 방법을 알면 새로운 API 연동이 훨씬 빨라집니다. 전체를 읽으려 하지 말고, 필요한 부분만 찾아서 깊이 읽으세요. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - API 문서는 빠른 시작 가이드부터 따라 해보세요 - Postman으로 문서의 예시를 직접 실행해보면 이해가 빠릅니다 - 잘 안 되면 문서의 FAQ나 커뮤니티를 확인하세요 --- ## 7. 무료 공공 API 소개 김개발 씨는 포트폴리오 프로젝트를 만들고 싶었습니다. 하지만 데이터가 없었습니다. 박시니어 씨가 말했습니다. "공공 API 써보세요. 무료로 다양한 데이터를 쓸 수 있어요." 김개발 씨는 무료로 쓸 수 있는 API가 있다는 사실에 놀랐습니다. **공공 API**는 누구나 무료로 사용할 수 있는 API입니다. 날씨, 환율, 도서 정보, 영화 정보 등 다양한 데이터를 제공합니다. 회원가입만 하면 API 키를 받을 수 있고, 실제 서비스처럼 데이터를 주고받을 수 있습니다. 포트폴리오나 학습용 프로젝트에 활용하기 좋습니다. 다음 코드를 살펴봅시다. ```python import requests # 1. JSONPlaceholder - 가짜 REST API (연습용) response = requests.get("https://jsonplaceholder.typicode.com/posts/1") post = response.json() print(f"게시글 제목: {post['title']}") # 2. Open Weather Map - 날씨 정보 (API 키 필요) api_key = "your_api_key" city = "Seoul" weather_url = f"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={api_key}&units=metric" response = requests.get(weather_url) weather = response.json() print(f"서울 온도: {weather['main']['temp']}도") # 3. 공공데이터포털 - 한국 정부 데이터 # 예: 전국 도서관 정보, 대기오염 정보 등 # https://www.data.go.kr 에서 API 신청 ``` 김개발 씨는 날씨 앱을 만들고 싶었습니다. 하지만 날씨 데이터를 어디서 구하지? 직접 기상청에 연락해야 하나? 비용이 얼마나 들까? 고민이 많았습니다. 박시니어 씨가 웃으며 말했습니다. "OpenWeatherMap 같은 무료 API가 많아요. 회원가입하고 API 키 받으면 끝이에요." 그렇다면 **무료 공공 API**에는 어떤 것들이 있을까요? 공공 API를 이해하는 좋은 비유는 공공 도서관입니다. 도서관은 누구나 무료로 책을 빌릴 수 있습니다. 다만 회원증을 만들어야 하고, 한 번에 빌릴 수 있는 권수에 제한이 있습니다. 공공 API도 똑같습니다. 무료지만 API 키를 받아야 하고, 하루에 호출할 수 있는 횟수에 제한이 있습니다. 공공 API가 등장하기 전에는 어땠을까요? 개발자들은 데이터를 직접 수집해야 했습니다. 날씨 정보가 필요하면 기상청 사이트를 크롤링하거나, 직접 계약을 맺어야 했습니다. 영화 정보가 필요하면 영화관 사이트를 일일이 파싱해야 했습니다. 시간도 오래 걸리고 법적 문제가 생길 수도 있었습니다. 더 큰 문제는 초보 개발자의 학습이었습니다. 실제 데이터 없이 API 개발을 배우기 어려웠습니다. 가짜 데이터를 직접 만들어야 했는데, 이것도 쉽지 않았습니다. 바로 이런 문제를 해결하기 위해 **무료 공공 API**가 많이 등장했습니다. 가장 유명한 것이 **JSONPlaceholder**입니다. 이것은 연습용 가짜 REST API입니다. 게시글, 댓글, 사용자 데이터를 제공합니다. 회원가입도 필요 없고, 무제한으로 사용할 수 있습니다. API 개발을 처음 배울 때 최고의 선택입니다. 실제 데이터가 필요하면 **OpenWeatherMap**을 추천합니다. 전 세계 20만 개 도시의 날씨 정보를 제공합니다. 무료 플랜은 하루 1000번 호출할 수 있습니다. 개인 프로젝트에는 충분한 양입니다. 회원가입 후 API 키를 받으면 바로 사용할 수 있습니다. 한국 데이터가 필요하면 **공공데이터포털**을 확인하세요. 정부에서 운영하는 사이트로, 전국 도서관 정보, 대기오염 정보, 지하철 실시간 도착 정보 등 수천 개의 API를 제공합니다. 회원가입 후 API를 신청하면 승인까지 1-2일 걸립니다. 위의 코드를 한 줄씩 살펴보겠습니다. JSONPlaceholder는 API 키가 필요 없습니다. 바로 URL로 요청하면 응답이 옵니다. 게시글, 댓글, 사용자 등 다양한 엔드포인트를 제공합니다. 연습하기에 완벽합니다. OpenWeatherMap은 API 키가 필요합니다. 사이트에서 회원가입 후 대시보드에서 API 키를 복사하면 됩니다. URL에 `appid` 파라미터로 API 키를 전달합니다. `units=metric`은 섭씨 온도를 사용하겠다는 의미입니다. 공공데이터포털은 각 API마다 사용법이 다릅니다. 문서를 참고해서 필요한 파라미터를 전달해야 합니다. 실제 현업에서는 어떻게 활용할까요? 많은 스타트업이 초기에는 공공 API를 활용합니다. 날씨 기반 추천 서비스를 만든다면 OpenWeatherMap으로 시작합니다. 서비스가 성장하면 유료 플랜으로 전환하거나, 더 전문적인 기상 데이터 API로 바꿉니다. 이렇게 빠르게 프로토타입을 만들고 검증할 수 있습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수는 무료 API의 제한을 무시하는 것입니다. 하루 1000번 호출 제한이 있는데, 무한 루프를 돌려서 순식간에 제한에 걸리는 경우가 많습니다. 또한 무료 API는 갑자기 서비스가 중단될 수도 있습니다. 실제 서비스에 사용하려면 유료 플랜을 고려하거나, 대안 API를 미리 찾아두어야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 김개발 씨는 OpenWeatherMap으로 날씨 앱을 완성했습니다. 포트폴리오에 올리니 면접에서 좋은 반응을 받았습니다. 무료 공공 API를 활용하면 실제 데이터로 프로젝트를 만들 수 있습니다. 학습용으로도, 포트폴리오용으로도 훌륭합니다. 여러분도 오늘 배운 API들을 활용해서 멋진 프로젝트를 만들어보세요. **실전 팁** 💡 - 무료 API는 호출 제한이 있으니 캐싱을 활용하세요 - API 키는 환경변수로 관리해서 GitHub에 올라가지 않게 주의하세요 - 더 많은 무료 API는 "public-apis" GitHub 저장소에서 찾을 수 있습니다 --- 이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

카테고리: Python

언어: Python

태그: Python, API, REST, JSON, HTTP

작성자: AI Generated

프리미엄 콘텐츠 - 3개월 무료 체험 가능

CodeDeck

API 개념과 JSON 데이터 완벽 가이드

목차

1. API란 무엇인가?

2. REST API 개념 이해

3. HTTP 메서드 (GET, POST)

4. JSON 데이터 구조

5. JSON vs CSV 비교

6. API 문서 읽는 법

7. 무료 공공 API 소개

댓글 (0)

함께 보면 좋은 카드 뉴스

Helm 마이크로서비스 패키징 완벽 가이드

보안 아키텍처 구성 완벽 가이드

AWS Organizations 완벽 가이드

AWS KMS 암호화 완벽 가이드

AWS Secrets Manager 완벽 가이드