API를 처음 만나는 행정 실무자

브라우저 주소를 바꿔 도서관 목록을 조회하고, 요청과 응답의 관계를 설명하는 것이 목표입니다. 실제 서비스의 인증키를 신청하기 전에 내 PC의 연습 API로 성공·오류·페이지 나누기를 경험합니다. 이 API는 공공데이터포털 서버가 아닙니다.

실습 키트를 압축 해제하고 Python 3.10 이상을 준비하세요. 앞 교재에서 데이터를 수정했다면 원본 sample.csv를 복원하고 변환부터 다시 실행합니다. 스마트폰에서는 개념과 교재를 읽고, 실행은 PC에서 진행하세요.

API는 프로그램이 다른 프로그램에 정해진 형식으로 요청하는 접점입니다. 이번 예제의 계약은 “GET으로 도서관을 조회하면 JSON을 돌려준다”입니다. API가 반드시 AI를 뜻하지는 않습니다.

요소	예시	뜻
메서드	GET	조회 요청
주소	/api/libraries	어떤 자료를 요청하는지
쿼리	city=해솔시	조회 조건
상태 코드	200 / 400	HTTP 수준의 성공 / 잘못된 요청
응답 본문	items 배열	실제 돌려받은 데이터

GET 조회와 POST 저장은 역할이 다릅니다. 다른 서비스에서 POST 예시를 보았다고 조회 주소에 그대로 적용하지 마세요. 실제 API는 HTTP 200이어도 본문 안에 오류 코드가 있을 수 있어, 상태 코드와 본문을 모두 확인합니다.

tech-practice 폴더에서 아래 중 운영체제에 맞는 명령 하나를 실행합니다.

py server.py

python3 server.py

터미널에 표시된 주소를 열고, 이어서 아래 주소를 브라우저 주소창에 입력합니다.

http://127.0.0.1:8765/api/libraries

127.0.0.1은 지금 쓰는 컴퓨터 자신입니다. 친구나 휴대전화에 이 주소를 보내도 내 PC에 접속하는 것이 아닙니다. 연습 서버는 외부에 공개하지 않도록 이 주소에만 연결합니다.

성공 확인: total은 6, page는 1, limit은 3, items는 3개입니다. 목록이 3개만 보인다고 전체가 3개인 것은 아닙니다.

다음 주소를 차례로 열어 응답을 비교하세요. 주소창에서 한글이 %가 포함된 문자열로 바뀌는 것은 URL 인코딩입니다.

http://127.0.0.1:8765/api/libraries?city=해솔시&page=1&limit=2
http://127.0.0.1:8765/api/libraries?city=해솔시&page=2&limit=2

첫 응답은 전체 3곳 중 2곳, 두 번째 응답은 나머지 1곳입니다. ?는 조건의 시작, &는 조건 사이의 구분입니다. total은 조건에 맞는 전체 개수이고 items.length는 이번 응답의 개수입니다.

직접 계산: 첫 페이지 좌석 합계는 180석, 두 번째는 20석입니다. 두 페이지를 합쳐야 해솔시 200석입니다. 대량 자료를 가져올 때 첫 페이지의 일부만 보고 전체 통계라고 보고하는 실수를 피하세요.

http://127.0.0.1:8765/api/libraries?limit=0

응답 본문에는 limit 범위 오류가 나옵니다. 브라우저 개발자 도구의 Network(네트워크)를 열고 새로고침한 뒤 이 요청을 선택하면 상태 400도 확인할 수 있습니다. 정상 주소로 바꾸면 200으로 돌아옵니다.

city=없는도시는 잘못된 문법이 아니므로 200과 빈 배열이 나옵니다. “검색 결과 없음”과 “서버 고장”을 구별해야 화면에서 올바른 안내를 할 수 있습니다.

실제 서비스에서 만날 코드	첫 확인
401 / 403	인증키, 이용 신청 승인, 접근 권한
404	문서의 정확한 주소와 경로
429	호출 한도, 재시도 간격
5xx	제공 서버 상태, 일시 장애

이 연습 서버가 위 모든 오류를 재현하는 것은 아닙니다. 400·404와 빈 결과를 직접 확인하고, 나머지는 실제 API 연동 시 구별할 기준으로 알아둡니다.

연습 대시보드는 dashboard/data/libraries.json 파일을 읽습니다. /api/libraries는 같은 파일을 읽고 조건에 맞게 골라 응답합니다. 화면과 API가 자료를 공유하지만, 화면이 자동으로 API를 호출하도록 구성한 것은 아닙니다.

AI에게 이렇게 요청해 확장할 수 있습니다.

현재 app.js의 파일 조회를 /api/libraries 조회로 바꾸는 방안을 설명해줘.
limit=100이어도 모든 페이지를 가져오도록 하고,
HTTP 오류와 items 누락을 검사해줘.
먼저 파일 기반 버전과 서버가 필요한 버전의 차이를 설명해줘.
수정 전에 원본을 백업하고, 실패하면 오류를 화면에 보여줘.

다음 배포 교재는 서버가 필요 없는 파일 기반 원본 버전을 사용합니다. API 연결 버전을 정적 호스팅에 그대로 올리면 /api/libraries가 없어 실패합니다. 서버 코드와 정적 파일은 배포 방식이 다르다는 점이 이 단계의 핵심입니다.

• 연결 거부: 서버를 실행한 터미널이 열려 있는지 확인합니다.
• 포트 사용 중: 앞 실습의 서버가 켜져 있다면 그대로 쓰거나 그 터미널에서 Ctrl+C로 종료한 뒤 다시 실행합니다.
• JSON 대신 HTML: 오타가 있는 경로의 404 페이지인지 확인합니다.
• 실제 외부 API에서 CORS 오류: 브라우저 접근 허용 정책 문제일 수 있습니다. 인증키를 프런트엔드에 넣는 우회 대신 서버에서 요청하는 구조를 검토합니다.

서버는 Ctrl+C로 끝납니다. 파일을 변경하지 않았다면 추가 복원은 필요 없습니다. 주소 전체에 인증키가 있는 실제 요청은 화면 캡처나 공개 질문에 붙이지 마세요.

• GET·주소·쿼리·응답을 내 말로 설명했다.
• 두 페이지를 합쳐 3곳·200석임을 확인했다.
• HTTP 400과 정상적인 빈 결과를 구별했다.
• 정적 파일 배포와 API 서버 배포가 다름을 이해했다.

다음은 실제 공공데이터를 찾고, 출처를 남기며 CSV를 같은 대시보드 형식으로 바꾸는 실습입니다.

• MDN HTTP 개요
• MDN HTTP 응답 상태 코드
• Python http.server: 이 실습용 서버를 공용 운영 서버로 쓰지 않는 이유.