Hoppscotch는 REST·GraphQL·실시간 API 요청을 보내고 응답을 검사하는 무료 오픈소스 프로그램입니다. 최신 26.8.2 데스크톱 앱을 Windows, macOS와 Linux에 설치할 수 있습니다.
메서드와 URL을 입력해 첫 GET 요청을 보내고, 헤더·인증·본문 설정과 컬렉션 저장, 응답 테스트까지 진행합니다.
Hoppscotch는 어떤 프로그램인가요?
API 엔드포인트에 요청을 보내 상태 코드, 처리 시간, 헤더와 JSON·원문 응답을 확인하는 개발 도구입니다.
컬렉션, 환경 변수, 스크립트, 테스트와 Runner를 이용해 반복 가능한 API 점검 작업을 만들 수 있습니다.
Hoppscotch REST 요청·응답·컬렉션 화면
공식 저장소와 공식 문서의 실제 UI입니다. 메서드·URL·Send, 요청 탭, JSON 응답, 컬렉션과 환경·인스턴스 선택 화면을 확인할 수 있습니다.
| Windows 설치형 | x64 MSI |
|---|---|
| Windows 포터블 | x64 ZIP |
| 라이선스 | MIT |
| 프로토콜 | REST · GraphQL · Realtime |
| 요청 | Parameters · Headers · Body |
| 인증 | Basic · Bearer · OAuth 2.0 |
| 관리 | 컬렉션 · 환경 변수 |
| 검증 | Scripts · Tests · Runner |
Windows 설치형과 포터블 선택
Windows 64비트 PC에서 일반적으로 설치해 쓸 때는 44.6MB MSI를 선택합니다. 시작 메뉴 등록과 업데이트 관리가 필요한 개발 PC에 알맞습니다.
설치 권한이 없거나 별도 폴더에서 실행하려면 44.3MB 포터블 ZIP을 받습니다. 압축을 모두 푼 뒤 실행 파일을 시작해야 설정과 임시 파일이 정상적으로 저장됩니다.
- 운영체제와 사용 방식에 맞는 설치 파일을 선택합니다.
- Windows MSI는 설치 마법사를 완료한 뒤 Hoppscotch를 실행합니다.
- REST 작업 공간에서 요청 메서드를 GET으로 선택합니다.
- 테스트할 API 주소를 URL 칸에 입력합니다.
- Parameters, Headers와 Authorization 값을 필요한 만큼 채웁니다.
- Send를 눌러 요청을 전송합니다.
- 응답 상태 코드, 처리 시간, 크기와 JSON 본문을 확인합니다.
- Save를 눌러 요청을 컬렉션에 저장합니다.
Hoppscotch는 어떤 프로그램인가요?
Hoppscotch는 REST, GraphQL과 실시간 통신 API를 만들고 시험하는 무료 오픈소스 개발 도구입니다. 메서드와 주소를 지정해 요청을 보내고 응답 상태, 헤더와 본문을 한 화면에서 확인할 수 있습니다.
요청을 컬렉션과 폴더로 정리하고 환경 변수를 사용하며 사전 요청 스크립트와 응답 테스트를 붙일 수 있습니다. 브라우저 웹 앱과 Windows·macOS·Linux 데스크톱 앱을 제공해 개발 방식에 맞춰 선택할 수 있습니다.
Windows MSI 설치
Hoppscotch_win_x64.msi을 실행하고 Windows가 표시하는 게시자와 설치 위치를 확인합니다. 설치를 마치면 시작 메뉴에서 Hoppscotch를 열고 데스크톱 앱 정보에 26.8.2 계열 버전이 표시되는지 봅니다.
데스크톱 버전은 연도의 마지막 두 자리를 사용하므로 웹 릴리스 2026.8.2는 앱에서 26.8.2로 표시됩니다. 버전 숫자가 달라 보이더라도 이 규칙으로 같은 릴리스인지 확인할 수 있습니다.
포터블 ZIP 실행
Hoppscotch_Cloud_win_x64_portable.zip을 다운로드한 뒤 쓰기 가능한 전용 폴더에 모두 압축 해제합니다. ZIP 파일 안에서 실행하면 구성 파일을 찾거나 저장하는 과정에서 문제가 생길 수 있습니다.
회사 PC처럼 설치가 제한된 환경에서 유용하지만 실행 파일과 같은 폴더의 구성 요소를 함께 보관해야 합니다. 새 버전으로 바꿀 때는 기존 폴더를 덮어쓰기 전에 컬렉션과 환경 데이터를 내보내 두세요.
macOS와 Linux 파일 선택
Apple Silicon Mac은 aarch64 DMG를, Intel Mac은 x64 DMG를 선택합니다. DMG를 열어 앱을 Applications 폴더로 옮긴 뒤 처음 실행할 때 macOS의 열기 확인 창을 승인합니다.
Debian·Ubuntu 계열은 DEB, 배포판과 관계없이 단일 파일로 실행하려면 x64 AppImage를 사용할 수 있습니다. AppImage는 실행 권한을 준 뒤 시작하고, 메뉴 등록 여부는 사용하는 데스크톱 환경에서 확인합니다.
첫 GET 요청 보내기
REST 작업 공간에서 메서드를 GET으로 두고 응답을 확인할 수 있는 API 엔드포인트를 입력합니다. Parameters 탭에서 키와 값을 추가하면 URL 쿼리 문자열에 반영되는지 미리보기로 확인할 수 있습니다.
Send를 누른 뒤 아래 응답 영역에서 200 같은 상태 코드, 처리 시간과 응답 크기를 먼저 봅니다. JSON 탭에서 본문 구조를 펼쳐 보고 Raw와 Headers 탭에서 원문과 응답 헤더를 비교하면 첫 요청이 완료됩니다.
POST JSON 본문 전송
메서드를 POST로 바꾸고 Body 탭에서 콘텐츠 형식을 application/json으로 선택합니다. JSON 편집기에 서버가 요구하는 필드와 값을 입력하고 문법 오류 표시가 없는지 확인합니다.
Headers에서 Content-Type이 중복으로 들어가지 않았는지 본 뒤 Send를 누릅니다. 응답 본문에 전송한 값이 반영됐는지 확인하고 400 오류가 나오면 필드 이름, 자료형과 필수값을 API 문서와 대조합니다.
헤더와 인증 설정
Headers 탭에는 API 키처럼 서버가 요구하는 헤더 이름과 값을 입력합니다. Authorization 탭에서는 None, Basic, Bearer Token, OAuth 2.0 등 API 방식에 맞는 유형을 선택합니다.
토큰을 요청 본문이나 공유 가능한 URL에 직접 넣지 말고 환경 변수로 분리합니다. 팀 컬렉션을 공유하기 전에는 현재값과 초기값이 어떻게 저장되는지 확인해 비밀값이 내보내기 파일에 포함되지 않게 해야 합니다.
환경 변수로 주소와 토큰 재사용
Environments에서 개발·스테이징·운영 환경을 각각 만들고 base_url, api_token 같은 변수를 등록합니다. 요청 URL과 헤더에서 변수 문법을 사용하면 환경을 바꿀 때 여러 요청을 일일이 수정하지 않아도 됩니다.
오른쪽 위 환경 선택 메뉴에서 현재 환경을 고른 뒤 변수 미리보기로 실제 치환 여부를 확인합니다. 빈 현재값은 초기값으로 대체될 수 있으므로 운영 요청 전에는 선택한 환경과 값이 맞는지 다시 봅니다.
컬렉션과 폴더에 요청 저장
Save를 누르고 컬렉션, 폴더와 요청 이름을 지정합니다. 사용자 조회, 생성, 수정처럼 API 기능별 폴더로 나누면 메서드 색상과 이름만 보고도 필요한 요청을 찾기 쉽습니다.
저장한 요청을 다시 열어 URL, 헤더, 본문과 테스트가 유지됐는지 확인합니다. 수정 뒤에는 저장 상태 표시가 바뀌는지 보고, 중요한 컬렉션은 내보내기 파일도 별도로 보관하세요.
cURL과 OpenAPI 가져오기
Importer에서 기존 cURL 명령을 붙여 넣으면 메서드, URL, 헤더와 본문을 요청으로 변환할 수 있습니다. 가져온 뒤 줄바꿈, 따옴표와 파일 경로가 현재 운영체제에 맞게 해석됐는지 확인합니다.
OpenAPI 문서를 가져오면 엔드포인트를 컬렉션 구조로 정리할 수 있습니다. 서버 주소와 인증 정의가 여러 개라면 사용할 환경을 선택하고, 생성된 요청 하나를 실제로 보내 응답까지 확인한 뒤 나머지를 활용하세요.
응답 본문과 헤더 확인
응답 영역의 JSON 보기는 객체와 배열을 접어 구조를 파악하기 좋습니다. Raw는 서버가 보낸 원문을 확인하고 Headers는 콘텐츠 형식, 캐시와 요청 추적 값을 살펴볼 때 사용합니다.
상태 코드가 성공이어도 응답 본문에 오류 정보가 포함될 수 있습니다. 기대한 필드가 있는지, 자료형과 값이 맞는지 확인하고 필요하면 응답을 파일로 내려받거나 클립보드에 복사해 비교합니다.
사전 요청 스크립트와 테스트
Pre-request Script에서 시간값이나 난수를 만들고 환경 변수를 갱신하면 요청 직전에 필요한 동적 값을 준비할 수 있습니다. 스크립트는 저장된 요청과 함께 실행되므로 사용하는 변수 이름을 명확히 적습니다.
Tests에서는 응답 상태 코드와 JSON 값을 검사합니다. Send 뒤 Test Results에서 통과·실패 항목을 확인하고, 실패하면 응답 본문과 실제 자료형을 먼저 살펴본 뒤 조건을 수정합니다.
컬렉션 Runner 사용
Runner에서 실행할 컬렉션과 환경을 선택하면 여러 요청을 정해진 순서로 실행할 수 있습니다. 인증 요청에서 만든 변수를 다음 요청이 사용한다면 사전 요청과 테스트 스크립트의 변수 갱신 순서를 확인합니다.
CSV 또는 JSON 데이터 파일로 여러 입력값을 바꿔 실행할 때는 열 이름과 변수 이름을 일치시킵니다. 완료 뒤 각 요청의 상태와 테스트 결과를 보고 실패한 반복 회차의 입력값을 따로 확인합니다.
GraphQL 요청 시험
GraphQL 작업 공간에서 엔드포인트를 입력하고 스키마를 불러옵니다. Query 편집기에 필요한 필드와 변수를 작성하고 Headers에 인증값을 설정한 뒤 요청을 보냅니다.
문서 패널에서 타입과 필드를 확인하고 응답의 errors 배열과 data 객체를 함께 봅니다. HTTP 200이어도 GraphQL 오류가 담길 수 있으므로 상태 코드만으로 성공을 판단하지 않습니다.
WebSocket과 실시간 연결
Realtime 작업 공간에서 WebSocket 주소를 입력해 연결하고 서버가 요구하는 메시지를 전송합니다. 연결 상태, 송신 메시지와 수신 메시지를 시간 순서로 확인합니다.
연결이 바로 끊기면 ws와 wss 프로토콜, 인증 헤더 또는 쿼리값, 서버의 Origin 정책을 확인합니다. 기업망에서는 프록시가 WebSocket 업그레이드를 막는지도 네트워크 담당자와 확인해야 합니다.
브라우저 CORS 오류 구분
웹 앱에서만 요청이 막히고 데스크톱 앱이나 서버 도구에서는 성공하면 브라우저 CORS 제한일 가능성이 큽니다. 개발자 도구 메시지에서 preflight와 Access-Control-Allow-Origin 응답 헤더를 확인합니다.
데스크톱 앱을 사용하거나 Hoppscotch Agent·프록시 설정을 올바르게 구성할 수 있습니다. 서버가 허용할 출처와 메서드를 관리할 수 있다면 임의 프록시보다 서버 CORS 설정을 바로잡는 편이 안전합니다.
로컬 API 연결 실패 해결
localhost 주소가 거부되면 API 서버가 실행 중인지, 포트와 HTTP·HTTPS가 맞는지 먼저 확인합니다. 컨테이너 안 서비스라면 호스트에 공개한 포트와 애플리케이션이 듣는 인터페이스를 구분합니다.
자체 서명 인증서를 쓰는 HTTPS 개발 서버는 인증서 신뢰 오류가 날 수 있습니다. 인증서 경고를 무시하기 전에 발급 대상과 유효기간을 확인하고 개발용 인증서를 운영체제 신뢰 저장소에 올바르게 등록합니다.
401과 403 응답 해결
401은 토큰 누락, 만료 또는 인증 방식 불일치부터 확인합니다. Authorization 유형, Bearer 접두어와 선택한 환경의 토큰값을 보고 새 토큰으로 요청을 다시 보냅니다.
403은 인증은 됐지만 권한이나 정책이 부족할 때 발생할 수 있습니다. 계정 역할, API 범위, 리소스 소유권과 서버의 IP 제한을 확인하고 응답 본문의 오류 코드를 기록합니다.
요청 시간이 초과될 때
응답이 늦으면 데스크톱 설정의 연결 제한 시간과 서버 처리 시간을 비교합니다. 같은 엔드포인트에 작은 입력으로 요청해 네트워크 지연인지 서버 작업량인지 구분합니다.
프록시를 사용한다면 직접 연결과 결과를 비교하고 DNS, VPN과 방화벽 상태를 확인합니다. 제한 시간을 무작정 늘리기보다 서버 로그의 요청 도착 시각과 응답 완료 시각을 함께 보는 것이 원인을 찾기 쉽습니다.
데이터를 내보내고 업데이트하기
컬렉션과 환경을 파일로 내보내면 새 버전 설치나 다른 PC 이동 전에 복구 자료를 만들 수 있습니다. 비밀 토큰과 운영 주소가 포함됐는지 확인한 뒤 암호화된 저장소에 보관합니다.
현재 데스크톱 릴리스는 26.8.2입니다. 앱의 업데이트 설정이나 공식 릴리스에서 새 버전을 확인하고, 업데이트 뒤 저장된 요청·환경과 첫 GET 요청이 그대로 작동하는지 확인합니다.
첫 API 테스트 완료 확인
공개 테스트 API에 GET 요청을 보내 200 응답과 JSON 본문을 확인합니다. 그 요청을 새 컬렉션에 저장하고 base_url을 환경 변수로 바꾼 뒤 다시 보내 같은 결과가 나오는지 봅니다.
다음으로 간단한 상태 코드 테스트를 추가해 Test Results가 통과하는지 확인합니다. 요청, 응답, 저장, 변수와 테스트가 모두 이어지면 Hoppscotch의 기본 API 테스트 작업을 마친 것입니다.
자주 묻는 질문
Hoppscotch는 무료인가요?
네. Community Edition과 데스크톱 앱 소스는 MIT 라이선스로 공개되어 있으며 공식 릴리스의 설치 파일을 무료로 받을 수 있습니다.
Windows에서는 어떤 파일을 받나요?
일반 설치는 x64 MSI, 설치 권한 없이 폴더에서 쓰려면 Cloud x64 portable ZIP을 선택합니다.
웹 앱과 데스크톱 앱의 차이는 무엇인가요?
웹 앱은 설치 없이 사용하기 쉽고, 데스크톱 앱은 브라우저 CORS 제한과 로컬 API 연결을 다룰 때 유리합니다.
401 응답이 나오면 무엇을 확인하나요?
Authorization 유형, 토큰 만료, Bearer 접두어와 선택한 환경 변수 값을 확인합니다.
요청을 다른 PC로 옮길 수 있나요?
컬렉션과 환경을 내보내거나 계정 동기화를 사용할 수 있습니다. 내보내기 전에 비밀값 포함 여부를 확인하세요.
첫 GET 요청을 컬렉션에 저장하세요
Hoppscotch를 설치한 뒤 테스트 API에 GET 요청을 보내 상태와 JSON 응답을 확인하세요. 요청을 컬렉션에 저장하고 환경 변수와 간단한 테스트를 붙이면 반복 가능한 API 점검 작업이 완성됩니다.
공식 자료와 확인일
Hoppscotch 공식 데스크톱 안내 · Hoppscotch 데스크톱 v26.8.2-0 공식 릴리스 · Hoppscotch 공식 저장소 · Hoppscotch 공식 빠른 시작 | 2026-10-01T00:26:33.611908+09:00
