Insomnia — là gì, client REST và GraphQL trong phát triển

Insomnia là gì và các tính năng chính

Insomnia là ứng dụng đa nền tảng (Electron) để gửi yêu cầu HTTP và gỡ lỗi API. Nó được công ty Kong phát triển từ năm 2016 như một giải pháp thay thế cho Postman tập trung vào tốc độ và quyền riêng tư: dữ liệu được lưu cục bộ, đồng bộ đám mây là tùy chọn và yêu cầu đăng ký.

Giao diện và điều hướng

Cửa sổ chính được chia thành ba cột: bên trái là cây yêu cầu (Workspace), ở giữa là trình soạn thảo yêu cầu với các tab Params, Headers, Body, bên phải là bảng phản hồi với các chế độ Pretty, Raw và Preview. Chế độ tối được bật theo mặc định và các chủ đề tùy chỉnh được hỗ trợ thông qua biến CSS.

Tạo mã

Insomnia hỗ trợ xuất yêu cầu thành mã bằng hơn 20 ngôn ngữ và framework: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP và các ngôn ngữ khác. Bộ tạo mã xem xét tiêu đề, nội dung yêu cầu và loại xác thực, giúp tăng tốc tích hợp API vào mã ứng dụng.

Insomnia so với Postman: so sánh client API

Insomnia và Postman giải quyết cùng một nhiệm vụ nhưng với các ưu tiên khác nhau. Insomnia nhẹ hơn (~80 MB so với ~300 MB), khởi động nhanh hơn và hoạt động hoàn toàn ngoại tuyến mà không ép buộc đăng ký. Postman cung cấp hệ sinh thái trưởng thành hơn với giám sát, máy chủ mock và không gian làm việc nhóm.

Chọn công cụ phù hợp với nhiệm vụ

Đối với phát triển cá nhân và kiểm thử nhanh các điểm cuối, Insomnia thuận tiện hơn nhờ tính nhẹ và không cần đăng ký. Đối với làm việc nhóm với bộ sưu tập dùng chung, tích hợp CI/CD và giám sát API sản xuất, Postman vẫn là tiêu chuẩn của ngành.

Tổ chức không gian làm việc và môi trường

Không gian làm việc trong Insomnia chứa cây yêu cầu được chia thành các thư mục. Mỗi yêu cầu có thể thuộc loại HTTP, GraphQL, WebSocket hoặc gRPC. Hỗ trợ kéo thả, nhân bản và nhóm các yêu cầu theo nhãn màu. Tệp cấu hình không gian làm việc được lưu ở định dạng JSON.

Biến môi trường với kế thừa

Insomnia hỗ trợ môi trường lồng nhau (Sub Environments) kế thừa các biến của môi trường cha. Điều này cho phép xác định URL gốc trong môi trường toàn cục và chỉ ghi đè các tham số khác nhau cho các môi trường khác nhau. Các biến được thay thế bằng cú pháp {`{`}_variable${`}`}.

// Ví dụ về cấu trúc môi trường Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Làm việc với GraphQL trong Insomnia

Insomnia cung cấp một trong những trình soạn thảo GraphQL tốt nhất trong số các client API. Tab GraphQL Query cho phép viết truy vấn với tính năng tự động hoàn thành trường dựa trên schema đã tải. Ở bên phải, tài liệu về kiểu, trường và đối số được hiển thị theo thời gian thực.

Tải schema và Introspection

Schema được tải thông qua yêu cầu GraphQL Introspection đến điểm cuối. Insomnia lưu cache schema cục bộ và tự động cập nhật khi có thay đổi. Sau khi tải, tự động hoàn thành (Ctrl+Space), xác thực yêu cầu và xem trước các lỗi có thể xảy ra trước khi gửi sẽ khả dụng.

# Truy vấn GraphQL với biến trong Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Plugin và mở rộng tính năng

Insomnia Plugin Hub chứa hơn 100 plugin mở rộng chức năng của client. Plugin được cài đặt qua menu Preferences → Plugins hoặc thủ công qua npm. Các danh mục phổ biến bao gồm tạo dữ liệu kiểm thử, xuất sang nhiều định dạng và bộ xác thực phản hồi tùy chỉnh. Mỗi plugin đều trải qua quá trình kiểm duyệt bắt buộc trước khi xuất bản lên trung tâm nhà phát triển công khai.

Plugin phổ biến

• insomnia-plugin-faker — tạo dữ liệu giả (tên, email, điện thoại) cho các yêu cầu kiểm thử.
• insomnia-plugin-aws4 — ký các yêu cầu theo AWS Signature Version 4 để làm việc với Amazon API Gateway và S3.
• insomnia-plugin-utils — tiện ích để làm việc với ngày tháng, băm và mã hóa Base64 trực tiếp trong yêu cầu.

Plugin được viết bằng JavaScript và tương tác với Insomnia thông qua API template (response.*, request.*, environment.*). Việc phát triển plugin yêu cầu kiến thức cơ bản về Node.js và xuất bản qua gói npm có thẻ insomnia-plugin.

CLI và tự động hóa kiểm thử

Inso CLI là tiện ích console tích hợp trong Insomnia để chạy các yêu cầu và kiểm thử từ terminal. Inso chạy các yêu cầu riêng lẻ hoặc toàn bộ bộ sưu tập, xuất kết quả sang JSON và có thể tích hợp vào các pipeline CI/CD. Lệnh inso run collection thực thi tuần tự tất cả các yêu cầu trong một bộ sưu tập.

Ví dụ tích hợp vào GitHub Actions

Inso CLI hoạt động trong các container Docker và chế độ headless, cho phép sử dụng nó trong GitHub Actions và GitLab CI. Cấu hình khởi chạy được mô tả trong tệp YAML chỉ định đường dẫn đến bộ sưu tập đã xuất và môi trường. Các xác nhận (assertion) về mã trạng thái và nội dung phản hồi được hỗ trợ thông qua tập lệnh JavaScript.

# Workflow GitHub Actions với Inso CLI
- name: Run API tests
  run: npx insomnia-inso run collection
    --collection "Auth API"
    --env "Staging"
    --reporter junit
    --output reports/api-results.xml

Tích hợp Insomnia với Git và làm việc nhóm

Insomnia hỗ trợ đồng bộ hóa bộ sưu tập qua Git. Các tệp bộ sưu tập được lưu ở định dạng JSON và có thể được thêm vào kho lưu trữ của dự án. Insomnia cung cấp client Git tích hợp để xem thay đổi, tạo commit và giải quyết xung đột hợp nhất trực tiếp từ giao diện.

Thiết lập đồng bộ hóa Git

Để kết nối Git, hãy tạo một thư mục cục bộ có kho lưu trữ và chỉ định nó làm thư mục gốc trong cài đặt Insomnia. Ứng dụng tự động theo dõi các thay đổi trong tệp bộ sưu tập và hiển thị chúng trong bảng Version Control. Các thao tác chuẩn được hỗ trợ: commit, push, pull và xem diff giữa các phiên bản.

Làm việc nhóm qua Insomnia Cloud

Đối với các dự án không dùng Git, Insomnia cung cấp đồng bộ hóa đám mây qua Insomnia Cloud. Gói miễn phí bao gồm tối đa 3 thành viên nhóm và sao lưu tự động các bộ sưu tập. Các gói trả phí bổ sung quản lý quyền truy cập, kiểm toán thay đổi và hỗ trợ ưu tiên.

Design Mode và tạo đặc tả

Design Mode trong Insomnia cho phép tạo đặc tả API ở định dạng OpenAPI 3.0. Chế độ này hoạt động như một trình soạn thảo trực quan: xác định điểm cuối và schema dữ liệu mà không cần viết YAML thủ công. Đặc tả có thể được xuất sang JSON hoặc YAML.

Tạo bộ sưu tập từ OpenAPI

Insomnia nhập các đặc tả OpenAPI và tạo một bộ sưu tập yêu cầu cho mỗi điểm cuối. Đường dẫn và schema được chuyển đổi thành các yêu cầu HTTP sẵn sàng. Tính năng này hữu ích khi tích hợp với các microservice, nơi đặc tả được lưu trữ trong kho lưu trữ riêng của nhóm.

Gắn thẻ yêu cầu

Mỗi yêu cầu có thể được gán một nhãn màu: red, blue, green, orange, purple. Lọc theo thẻ hoạt động thông qua thanh tìm kiếm bất kể cấu trúc thư mục, giúp đơn giản hóa việc điều hướng trong các dự án có hàng trăm điểm cuối và nhiều mô-đun.

Design Mode và tạo đặc tả

Design Mode trong Insomnia cho phép tạo đặc tả API ở định dạng OpenAPI 3.0 ngay trong ứng dụng. Chế độ này hoạt động như một trình soạn thảo trực quan: xác định điểm cuối, schema dữ liệu và tham số mà không cần viết YAML thủ công. Đặc tả có thể được xuất sang JSON hoặc YAML để xuất bản vào kho lưu trữ.

Tạo bộ sưu tập từ OpenAPI

Insomnia nhập các đặc tả OpenAPI hiện có và tự động tạo một bộ sưu tập yêu cầu cho mỗi điểm cuối. Đường dẫn và schema được chuyển đổi thành các yêu cầu HTTP sẵn sàng với đúng kiểu dữ liệu. Tính năng này hữu ích khi tích hợp với các microservice, nơi đặc tả được lưu trữ và duy trì bởi một nhóm phát triển backend riêng.

Gắn thẻ và lọc yêu cầu

Để tổ chức số lượng lớn yêu cầu, Insomnia hỗ trợ gắn thẻ — mỗi yêu cầu có thể được gán một nhãn màu: red, blue, green, orange, purple. Lọc theo thẻ hoạt động thông qua thanh tìm kiếm bất kể cấu trúc thư mục, giúp đơn giản hóa việc điều hướng trong các dự án có hàng trăm điểm cuối và nhiều mô-đun chức năng API.