Insomnia는 REST, GraphQL, gRPC와 WebSocket API를 설계·호출·검사하는 무료 다운로드 데스크톱 프로그램입니다. 최신 13.3.0은 Windows 10 이상, macOS와 Linux용으로 배포됩니다.
API Collection을 만들고 GET 요청을 보낸 뒤 응답 상태와 JSON을 확인합니다. 환경 변수, 인증, OpenAPI Spec과 응답 검사까지 연결하면 반복 가능한 API 테스트를 구성할 수 있습니다.
Insomnia는 어떤 프로그램인가요?
HTTP 메서드, URL, 쿼리, 헤더, 인증과 요청 본문을 구성하고 서버의 상태 코드·헤더·본문을 한 화면에서 확인합니다.
API Collection에 요청, 환경, OpenAPI Spec과 스크립트를 함께 저장해 단일 호출부터 연속 테스트까지 관리합니다.
Insomnia API Collection·요청·OpenAPI·응답 검사 화면
Insomnia 공식 저장소와 Kong 공식 문서의 실제 UI입니다. 요청 편집, 응답, API Collection, OpenAPI Spec과 After-response 스크립트 화면을 확인할 수 있습니다.
| Windows | NSIS EXE |
|---|---|
| macOS | DMG |
| Linux | AppImage·DEB |
| 라이선스 | Apache-2.0 |
| 요청 | HTTP·GraphQL |
| 명세 | OpenAPI |
| 변수 | Environments |
| 검사 | After-response |
Windows 설치와 첫 REST 요청
Windows 10 이상 PC에서는 500.5MB NSIS 설치 파일을 실행합니다. 설치가 끝나면 Insomnia를 열고 로컬 작업은 Scratch Pad, 프로젝트 단위 관리는 Project에서 시작한 뒤 API Collection을 만듭니다.
첫 요청은 HTTP Request를 추가하고 GET 방식과 테스트 URL을 입력한 뒤 Send를 누릅니다. 오른쪽 응답 창에서 200 상태, 응답 시간, 헤더와 JSON 본문을 확인하면 설치와 기본 통신 확인이 끝납니다.
- 공식 Windows NSIS 설치 파일을 받습니다.
- 열려 있는 Insomnia를 종료하고 설치 파일을 실행합니다.
- 설치 후 Insomnia 13.3.0을 시작합니다.
- Scratch Pad 또는 Project에서 API Collection을 만듭니다.
- HTTP Request를 추가하고 GET을 선택합니다.
- 테스트할 HTTPS URL을 입력합니다.
- Send를 누르고 응답 상태와 JSON 본문을 확인합니다.
- 요청 이름을 바꾸고 Collection에 저장합니다.
Insomnia는 어떤 프로그램인가요?
Insomnia는 REST, GraphQL, gRPC, WebSocket과 Event Stream 요청을 만들고 API 응답을 검사하는 무료 다운로드 데스크톱 프로그램입니다. HTTP 메서드, URL, 쿼리, 헤더, 인증과 본문을 한 화면에서 구성할 수 있습니다.
API Collection 안에 요청, 폴더, 환경 변수와 OpenAPI 명세를 함께 보관합니다. 단일 요청뿐 아니라 Collection Runner, 요청 전 스크립트와 응답 후 검사로 반복 테스트도 구성할 수 있습니다.
Windows 설치 파일 선택
일반 Windows 사용자는 Insomnia.Core-nsis-13.3.0.exe을 선택합니다. 공식 문서는 Windows 10 이상을 요구하며, 설치 중 실행 중인 Insomnia가 열려 있으면 업데이트 파일을 바꾸지 못할 수 있으므로 먼저 종료합니다.
기본 설치는 사용자 계정의 AppData 아래에 들어갑니다. 전체 PC 사용자를 위한 설치나 별도 폴더가 필요할 때만 관리자 설치와 경로 옵션을 사용하고, 회사 PC에서는 조직의 설치 정책을 먼저 확인하세요.
macOS와 Linux 설치
macOS는 363.2MB DMG를 열어 Insomnia를 Applications로 옮깁니다. Linux에서는 591.3MB AppImage 또는 407.5MB DEB를 배포판에 맞춰 선택할 수 있습니다.
AppImage는 실행 권한을 준 뒤 시작하고, Debian·Ubuntu 계열은 DEB를 패키지 관리자로 설치합니다. 각 운영체제에서 첫 실행 후 About 또는 업데이트 화면에서 버전을 확인합니다.
Scratch Pad와 Project 선택
계정 동기화 없이 로컬에서 빠르게 요청을 시험하려면 Scratch Pad를 사용합니다. 팀과 프로젝트 단위로 API Collection, 명세와 환경을 관리하려면 Project를 만듭니다.
토큰과 비밀번호가 들어간 요청은 저장 위치와 동기화 범위를 먼저 확인하세요. 개인 테스트와 팀 공유 작업을 섞지 않으면 민감한 환경 값이 잘못 공유되는 일을 줄일 수 있습니다.
API Collection 만들기
Create에서 API Collection을 만들고 서비스나 API 이름을 입력합니다. 13.3부터 이전의 문서와 요청 컬렉션이 API Collection 하나로 합쳐져 요청, 환경과 OpenAPI Spec을 같은 작업 공간에서 다룹니다.
왼쪽 사이드바에는 기능이나 자원별 폴더를 만들고 요청 이름에 동작과 대상을 함께 적습니다. 예를 들어 사용자 목록 조회, 주문 생성처럼 결과가 바로 구분되는 이름이 관리하기 쉽습니다.
GET 요청 보내기
새 HTTP Request에서 GET을 선택하고 전체 URL을 입력합니다. Params 탭에는 page, limit 같은 쿼리 값을 각각 추가하고 체크박스로 포함 여부를 바꿀 수 있습니다.
Send를 누른 뒤 상태 코드가 200인지, 응답 시간이 비정상적으로 길지 않은지, JSON 필드가 예상한 구조인지 확인합니다. Preview와 Headers를 오가며 실제 Content-Type과 응답 서버 정보도 살펴봅니다.
POST JSON 본문 작성
POST 요청으로 바꾸고 Body에서 JSON을 선택한 뒤 API 문서의 필드 이름과 자료형에 맞춰 본문을 입력합니다. Content-Type 헤더가 application/json인지 확인하고 필수 필드를 빠뜨리지 않습니다.
400 응답이 나오면 서버 오류로 단정하지 말고 응답 본문의 validation 메시지, JSON 쉼표와 따옴표, 날짜 형식과 숫자·문자열 자료형을 먼저 대조합니다.
헤더와 인증 설정
Headers 탭에는 Accept, Content-Type과 사용자 정의 헤더를 넣습니다. Auth 탭에서는 Basic, Bearer Token, OAuth 2.0 등 API가 요구하는 인증 방식을 선택하고 해당 값을 입력합니다.
토큰을 요청마다 직접 붙여 넣기보다 환경 변수로 분리합니다. 만료된 토큰은 401, 권한 범위가 부족한 토큰은 403이 날 수 있으므로 재로그인만 반복하지 말고 만료 시각과 scope를 확인하세요.
환경 변수로 서버와 토큰 바꾸기
Environments에서 base_url, token 같은 값을 JSON 객체로 정의하고 요청 URL과 인증 칸에서 변수를 참조합니다. 개발, 스테이징과 운영용 sub-environment에는 서로 다른 값만 넣습니다.
같은 변수 이름이 여러 위치에 있으면 폴더, 선택한 collection sub-environment, collection base, global 환경 순서의 우선순위를 확인합니다. 엉뚱한 서버로 요청이 나가면 활성 환경 이름과 변수의 실제 출처부터 살펴보세요.
비밀 환경 변수 관리
비밀 값은 private global sub-environment의 Secret 유형과 vault를 사용하면 마스킹된 상태로 로컬 암호화할 수 있습니다. Preferences의 Security에서 vault key를 만들고 해당 private 환경을 선택합니다.
vault key를 잃으면 비밀 값을 복구할 수 없으므로 조직의 안전한 비밀 관리 절차에 따라 보관합니다. 화면 공유, 내보내기와 Git Sync 전에 토큰이 일반 텍스트 환경에 남아 있지 않은지 확인하세요.
cURL과 Postman 자료 가져오기
새 요청의 가져오기 메뉴에서 cURL 명령을 붙여 넣으면 메서드, URL, 헤더와 본문을 요청으로 변환합니다. File, URL 또는 Clipboard로 Postman 컬렉션, OpenAPI, Swagger, HAR와 WSDL도 가져올 수 있습니다.
가져온 직후에는 인증 값과 환경 변수가 현재 프로젝트에 맞는지 확인합니다. 원본 도구의 변수 문법이나 파일 경로가 그대로 동작하지 않을 수 있으므로 대표 요청 하나를 보내 결과를 검증한 뒤 전체 컬렉션을 사용하세요.
GraphQL 쿼리 실행
GraphQL Request를 만들거나 HTTP 요청 Body를 GraphQL로 바꾸면 Query와 Variables 영역이 나타납니다. 스키마 introspection이 가능하면 자동 완성과 인라인 검사가 쿼리 작성을 돕습니다.
쿼리에는 필요한 필드만 넣고 값은 Variables에 JSON으로 분리합니다. HTTP 상태가 200이어도 GraphQL 응답의 errors 배열에 실패 이유가 들어갈 수 있으므로 data만 확인하고 끝내지 마세요.
OpenAPI Spec 편집과 요청 생성
API Collection의 Spec 탭에서 OpenAPI 문서를 작성하거나 가져오면 미리보기, lint 오류와 schema를 함께 확인할 수 있습니다. 서버 URL과 인증 변수를 먼저 정의합니다.
Spec 탭의 Generate에서 Requests를 선택하면 endpoint별 요청이 같은 API Collection에 생성됩니다. 생성 후 각 요청의 경로 변수, request body 예시와 인증을 채우고 실제 서버 응답을 확인합니다.
응답 헤더와 시간 확인
응답 패널의 Preview에서 본문을 보고 Headers에서 Content-Type, 캐시, 요청 추적 ID와 rate-limit 정보를 확인합니다. 상태 코드 옆의 응답 시간과 크기는 이전 실행과 비교할 때 기준이 됩니다.
204 응답은 본문이 없어도 정상일 수 있고, 304는 캐시 조건에 따른 결과입니다. 상태 코드 하나만 보지 말고 사용한 메서드와 API 문서가 약속한 응답 형식을 함께 비교하세요.
요청 전·응답 후 스크립트
Pre-request 스크립트로 변수나 헤더, 본문을 실행 직전에 조정할 수 있습니다. After-response 스크립트에서는 응답 JSON을 읽고 예상 상태나 필드 값을 검사합니다.
스크립트가 요청 결과를 바꿀 수 있으므로 팀이 이해할 이름과 설명을 남깁니다. 실패 시 Network나 Console 정보와 스크립트 오류 위치를 확인하고, 동적 값 없이 같은 요청을 보내 서버 문제와 스크립트 문제를 구분합니다.
Collection Runner로 연속 실행
여러 요청을 정해진 순서로 확인할 때 Collection Runner를 사용합니다. 실행할 요청, 반복 데이터와 환경을 선택하고 앞 요청의 응답 값을 다음 요청에서 참조할 수 있습니다.
삭제나 결제가 포함된 요청을 운영 환경에서 한꺼번에 실행하지 않도록 대상 환경과 순서를 다시 확인합니다. 테스트 데이터 생성과 정리 요청을 구분하고 실패한 단계의 상태와 응답을 기록합니다.
401·403 인증 오류 해결
401이면 Authorization 헤더가 실제 전송됐는지, 토큰 앞에 Bearer와 공백이 필요한지, 토큰 만료와 서버 시간이 맞는지 확인합니다. 403이면 로그인보다 계정 역할, scope와 대상 자원 권한을 확인합니다.
환경을 바꾼 직후에는 토큰과 base_url이 같은 서버 쌍인지 확인합니다. 개발 서버 토큰으로 운영 URL을 호출하면 형식은 맞아도 권한 오류가 날 수 있습니다.
SSL 인증서와 프록시 오류
사내 프록시 환경에서는 Preferences의 프록시 설정과 운영체제 인증서 신뢰 구성을 확인합니다. 자체 서명 인증서 문제를 무조건 검증 해제로 넘기기 전에 인증서 체인, 호스트 이름과 유효 기간을 검사합니다.
timeout이면 DNS, VPN, 프록시, 포트와 서버 상태를 차례로 확인합니다. 동일 URL을 브라우저에서 열 수 있다는 사실만으로 API 메서드와 인증 경로까지 정상인 것은 아닙니다.
CORS와 데스크톱 요청 구분
Insomnia 데스크톱 요청이 성공하지만 웹 앱에서 CORS 오류가 나는 경우가 있습니다. CORS는 브라우저가 응답 사용을 제한하는 정책이므로 Insomnia 성공만으로 브라우저 배포가 정상이라고 판단할 수 없습니다.
웹 앱의 Origin, preflight OPTIONS와 서버의 Access-Control-Allow-* 응답을 확인합니다. API 자체 연결 문제와 브라우저 정책 문제를 분리하면 불필요하게 Insomnia 설정을 바꾸지 않아도 됩니다.
데이터 내보내기와 백업
API Collection 메뉴에서 Insomnia v5 또는 HAR 형식으로 내보낼 수 있고 Preferences > Data에서는 전체 데이터를 내보낼 수 있습니다. 다른 PC로 옮기기 전에 파일에 토큰, 쿠키와 개인 URL이 포함됐는지 확인합니다.
Git Sync를 쓴다면 비밀 값은 저장소에 들어가지 않도록 private 환경과 조직 규칙을 사용합니다. 내보낸 파일을 별도 테스트 프로젝트에 가져와 요청·환경·Spec이 모두 보이는지 확인해야 백업 완료로 볼 수 있습니다.
첫 API 테스트 완료 확인
GET 요청을 저장하고 개발 환경의 base_url 변수를 적용합니다. Send 후 200 상태, Content-Type과 JSON 핵심 필드를 확인하고 응답 후 검사 하나를 실행합니다.
같은 요청을 잘못된 토큰으로 보내 401을 확인한 뒤 정상 토큰으로 되돌립니다. 요청 이름, 환경과 검사 결과가 Collection에 남아 다시 실행할 수 있으면 첫 API 테스트 작업이 완료됩니다.
자주 묻는 질문
Insomnia는 무료로 다운로드할 수 있나요?
네. 공식 GitHub 릴리스에서 Windows, macOS와 Linux 데스크톱 앱을 무료로 받을 수 있습니다. 팀 협업과 기업 기능은 선택한 서비스 플랜에 따라 달라질 수 있습니다.
Windows에서는 어떤 파일을 받나요?
Windows 10 이상 일반 설치에는 Insomnia.Core-nsis-13.3.0.exe 파일을 선택합니다.
REST와 GraphQL을 모두 테스트할 수 있나요?
네. HTTP Request에서 REST 요청을 만들고 GraphQL 유형에서는 Query와 Variables, schema 기반 자동 완성을 사용할 수 있습니다.
토큰을 요청마다 입력해야 하나요?
아니요. 환경 변수나 private 환경의 Secret 값으로 분리하고 활성 환경을 바꿔 재사용할 수 있습니다.
Insomnia에서는 성공하는데 웹 앱에서 CORS 오류가 나는 이유는 무엇인가요?
Insomnia는 데스크톱 클라이언트라 브라우저 CORS 정책과 다릅니다. 서버의 Origin·preflight 응답 설정을 웹 앱 기준으로 확인해야 합니다.
GET 요청과 응답 검사까지 완료하세요
Insomnia를 설치한 뒤 API Collection에서 GET 요청을 만들고 환경 변수와 인증을 적용하세요. 상태 코드, 응답 헤더와 JSON을 확인하고 After-response 검사까지 저장하면 반복 실행할 수 있는 첫 API 테스트가 완성됩니다.
공식 자료와 확인일
Insomnia 13.3.0 공식 릴리스 · Insomnia Windows 공식 설치 문서 · Insomnia 공식 문서 · Insomnia API Collections 공식 문서 · Insomnia 공식 저장소 | 2026-10-01T01:11:08.246183+09:00
