Insomnia란 — 개발에서의 REST 및 GraphQL 클라이언트

Insomnia란 무엇이며 주요 기능

Insomnia는 HTTP 요청 전송과 API 디버깅을 위한 크로스 플랫폼 애플리케이션(Electron)입니다. 속도와 개인정보 보호에 중점을 둔 Postman의 대안으로 2016년부터 Kong사가 개발하고 있습니다. 데이터는 로컬에 저장되며 클라우드 동기화는 선택 사항이고 등록이 필요합니다.

인터페이스와 탐색

기본 창은 세 개의 열로 나뉩니다. 왼쪽은 요청 트리(Workspace), 중앙은 Params, Headers, Body 탭이 있는 요청 편집기, 오른쪽은 Pretty, Raw, Preview 모드가 있는 응답 패널입니다. 다크 테마가 기본으로 활성화되어 있으며 CSS 변수를 통한 사용자 정의 테마가 지원됩니다.

코드 생성

Insomnia는 요청을 20개 이상의 언어 및 프레임워크의 코드로 내보내는 것을 지원합니다: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP 등. 생성기는 헤더, 요청 본문, 인증 유형을 고려하므로 애플리케이션 코드에 API를 통합하는 속도가 빨라집니다.

Insomnia 대 Postman: API 클라이언트 비교

Insomnia와 Postman은 같은 작업을 해결하지만 우선순위가 다릅니다. Insomnia는 더 가볍고(약 80 MB 대 약 300 MB), 시작이 빠르며, 등록을 강요하지 않고 완전히 오프라인으로 작동합니다. Postman은 모니터링, mock 서버, 팀 워크스페이스를 갖춘 더 성숙한 생태계를 제공합니다.

작업에 맞는 도구 선택

개인 개발과 엔드포인트의 빠른 테스트에는 Insomnia가 가볍고 등록이 필요 없어 더 편리합니다. 공유 컬렉션, CI/CD 통합, 프로덕션 API 모니터링이 있는 팀 작업에서는 Postman이 업계 표준으로 남아 있습니다.

작업 공간과 환경 구성

Insomnia의 워크스페이스에는 폴더로 나뉜 요청 트리가 포함됩니다. 각 요청은 HTTP, GraphQL, WebSocket 또는 gRPC 유형일 수 있습니다. 끌어서 놓기, 복제, 색상 레이블로 요청 그룹화가 지원됩니다. 워크스페이스 구성 파일은 JSON 형식으로 저장됩니다.

상속이 있는 환경 변수

Insomnia는 부모의 변수를 상속하는 중첩 환경(Sub Environments)을 지원합니다. 이를 통해 전역 환경에서 기본 URL을 정의하고 다양한 환경에 대해 다른 매개변수만 재정의할 수 있습니다. 변수는 구문 {`{`}_variable${`}`}을 통해 대체됩니다.

// Insomnia 환경 구조의 예
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Insomnia에서 GraphQL 작업

Insomnia는 API 클라이언트 중 최고 수준의 GraphQL 편집기를 제공합니다. GraphQL Query 탭에서는 로드된 스키마를 기반으로 필드 자동 완성과 함께 쿼리를 작성할 수 있습니다. 오른쪽에는 유형, 필드, 인수에 대한 문서가 실시간으로 표시됩니다.

스키마 로드와 Introspection

스키마는 엔드포인트에 대한 GraphQL Introspection 요청을 통해 로드됩니다. Insomnia는 스키마를 로컬에 캐시하고 변경 시 자동으로 업데이트합니다. 로드 후 자동 완성(Ctrl+Space), 요청 검증, 전송 전 가능한 오류 미리보기를 사용할 수 있습니다.

# Insomnia에서 변수가 있는 GraphQL 쿼리
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

플러그인과 기능 확장

Insomnia Plugin Hub에는 클라이언트의 기능을 확장하는 100개 이상의 플러그인이 있습니다. 플러그인은 Preferences → Plugins 메뉴를 통해 또는 npm을 통해 수동으로 설치합니다. 인기 있는 카테고리에는 테스트 데이터 생성, 다양한 형식으로 내보내기, 사용자 정의 응답 검증기가 포함됩니다. 각 플러그인은 공개 개발자 허브에 게시되기 전에 필수 검토를 거칩니다.

인기 있는 플러그인

• insomnia-plugin-faker — 테스트 요청용 가짜 데이터(이름, 이메일, 전화번호) 생성.
• insomnia-plugin-aws4 — Amazon API Gateway 및 S3 작업을 위한 AWS Signature Version 4로 요청 서명.
• insomnia-plugin-utils — 요청에서 직접 날짜, 해싱, Base64 인코딩 작업을 위한 유틸리티.

플러그인은 JavaScript로 작성되며 템플릿 API(response.*, request.*, environment.*)를 통해 Insomnia와 상호작용합니다. 플러그인 개발에는 Node.js에 대한 기본 지식과 insomnia-plugin 태그가 있는 npm 패키지로 게시가 필요합니다.

CLI와 테스트 자동화

Inso CLI는 터미널에서 요청과 테스트를 실행하기 위해 Insomnia에 내장된 콘솔 유틸리티입니다. Inso는 개별 요청이나 전체 컬렉션을 실행하고 결과를 JSON으로 내보내며 CI/CD 파이프라인에 통합할 수 있습니다. inso run collection 명령은 컬렉션의 모든 요청을 순차적으로 실행합니다.

GitHub Actions 통합 예시

Inso CLI는 Docker 컨테이너와 헤드리스 모드에서 작동하므로 GitHub Actions와 GitLab CI에서 사용할 수 있습니다. 시작 구성은 내보낸 컬렉션과 환경의 경로를 지정하여 YAML 파일에 설명됩니다. JavaScript 스크립트를 통한 상태 코드와 응답 본문에 대한 어서션(assertion)이 지원됩니다.

# Inso CLI를 사용한 GitHub Actions 워크플로우
- name: Run API tests
  run: npx insomnia-inso run collection
    --collection "Auth API"
    --env "Staging"
    --reporter junit
    --output reports/api-results.xml

Insomnia와 Git 통합 및 팀 작업

Insomnia는 Git을 통한 컬렉션 동기화를 지원합니다. 컬렉션 파일은 JSON 형식으로 저장되며 프로젝트 저장소에 추가할 수 있습니다. Insomnia는 변경 사항 보기, 커밋 생성, 인터페이스에서 직접 병합 충돌 해결을 위한 내장 Git 클라이언트를 제공합니다.

Git 동기화 설정

Git을 연결하려면 저장소가 있는 로컬 폴더를 만들고 Insomnia 설정에서 루트 디렉터리로 지정하세요. 애플리케이션은 컬렉션 파일의 변경 사항을 자동으로 추적하여 Version Control 패널에 표시합니다. 커밋, 푸시, 풀, 버전 간 diff 보기 등 표준 작업이 지원됩니다.

Insomnia Cloud를 통한 팀 작업

Git이 없는 프로젝트의 경우 Insomnia는 Insomnia Cloud를 통한 클라우드 동기화를 제공합니다. 무료 요금제에는 팀원 최대 3명과 컬렉션 자동 백업이 포함됩니다. 유료 요금제는 액세스 관리, 변경 감사, 우선 지원을 추가합니다.

Design Mode와 사양 생성

Insomnia의 Design Mode는 OpenAPI 3.0 형식으로 API 사양을 만들 수 있게 해줍니다. 이 모드는 시각적 편집기처럼 작동합니다. YAML을 직접 작성하지 않고 엔드포인트와 데이터 스키마를 정의하세요. 사양은 JSON 또는 YAML로 내보낼 수 있습니다.

OpenAPI에서 컬렉션 생성

Insomnia는 OpenAPI 사양을 가져와 각 엔드포인트에 대한 요청 컬렉션을 만듭니다. 경로와 스키마는 준비된 HTTP 요청으로 변환됩니다. 이 기능은 사양이 팀의 별도 저장소에 저장되는 마이크로서비스와의 통합에 유용합니다.

요청 태깅

각 요청에 색상 레이블을 지정할 수 있습니다: red, blue, green, orange, purple. 태그별 필터링은 폴더 구조와 관계없이 검색 창을 통해 작동하므로 수백 개의 엔드포인트와 많은 모듈이 있는 프로젝트에서 탐색이 간편해집니다.

Design Mode와 사양 생성

Insomnia의 Design Mode는 애플리케이션 내에서 직접 OpenAPI 3.0 형식으로 API 사양을 만들 수 있게 해줍니다. 이 모드는 시각적 편집기처럼 작동합니다. YAML을 직접 작성하지 않고 엔드포인트, 데이터 스키마, 매개변수를 정의하세요. 사양은 저장소에 게시하기 위해 JSON 또는 YAML로 내보낼 수 있습니다.

OpenAPI에서 컬렉션 생성

Insomnia는 기존 OpenAPI 사양을 가져와 각 엔드포인트에 대한 요청 컬렉션을 자동으로 만듭니다. 경로와 스키마는 올바른 데이터 유형을 가진 준비된 HTTP 요청으로 변환됩니다. 이 기능은 사양을 별도의 백엔드 개발 팀이 저장하고 유지 관리하는 마이크로서비스와의 통합에 유용합니다.

요청 태깅과 필터링

많은 요청을 구성하기 위해 Insomnia는 태깅을 지원합니다 — 각 요청에 색상 레이블을 지정할 수 있습니다: red, blue, green, orange, purple. 태그별 필터링은 폴더 구조와 관계없이 검색 창을 통해 작동하므로 수백 개의 엔드포인트와 많은 기능적 API 모듈이 있는 프로젝트에서 탐색이 간편해집니다.