Insomnia — nedir, geliştirmede REST ve GraphQL istemcisi

Insomnia nedir ve temel özellikleri

Insomnia, HTTP istekleri göndermek ve API'lerde hata ayıklamak için çok platformlu bir uygulamadır (Electron). Hız ve gizliliğe odaklanan Postman alternatifi olarak 2016'dan beri Kong şirketi tarafından geliştirilmektedir: veriler yerel olarak saklanır, bulut senkronizasyonu isteğe bağlıdır ve kayıt gerektirir.

Arayüz ve gezinme

Ana pencere üç sütuna bölünmüştür: solda istek ağacı (Workspace), ortada Params, Headers, Body sekmeleriyle istek düzenleyicisi, sağda Pretty, Raw ve Preview modlarıyla yanıt paneli. Koyu tema varsayılan olarak etkindir ve CSS değişkenleri aracılığıyla özel temalar desteklenir.

Kod üretimi

Insomnia, bir isteğin 20'den fazla dilde ve framework'te koda dışa aktarılmasını destekler: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP ve diğerleri. Üretici; başlıkları, istek gövdesini ve kimlik doğrulama türünü dikkate alır, bu da API'nin uygulama koduna entegrasyonunu hızlandırır.

Insomnia vs Postman: API istemcilerinin karşılaştırması

Insomnia ve Postman aynı görevi çözer ancak farklı önceliklerle. Insomnia daha hafiftir (~80 MB'ye karşı ~300 MB), daha hızlı başlar ve kayıt zorlamadan tamamen çevrimdışı çalışır. Postman; izleme, mock sunucular ve ekip çalışma alanlarıyla daha olgun bir ekosistem sunar.

Göreve göre araç seçimi

Bireysel geliştirme ve uç noktaların hızlı testi için Insomnia, hafifliği ve kayıt gerektirmemesi sayesinde daha kullanışlıdır. Paylaşılan bir koleksiyon, CI/CD entegrasyonu ve üretim API'si izleme ile ekip çalışması için Postman sektör standardı olmaya devam eder.

Çalışma alanının ve ortamların düzenlenmesi

Insomnia'daki çalışma alanı, klasörlere ayrılmış bir istek ağacı içerir. Her istek HTTP, GraphQL, WebSocket veya gRPC türünde olabilir. Sürükle-bırak, çoğaltma ve isteklerin renkli etiketlerle gruplandırılması desteklenir. Çalışma alanı yapılandırma dosyası JSON formatında saklanır.

Miras alma ile ortam değişkenleri

Insomnia, üst öğenin değişkenlerini miras alan iç içe ortamları (Sub Environments) destekler. Bu, genel ortamda temel bir URL tanımlamayı ve farklı ortamlar için yalnızca farklı olan parametreleri yeniden tanımlamayı sağlar. Değişkenler {`{`}_variable${`}`} sözdizimiyle değiştirilir.

// Insomnia ortam yapısı örneği
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Insomnia'da GraphQL ile çalışma

Insomnia, API istemcileri arasında en iyi GraphQL düzenleyicilerinden birini sunar. GraphQL Query sekmesi, yüklenen şemaya dayalı olarak alan otomatik tamamlamayla sorgular yazmanıza olanak tanır. Sağda türler, alanlar ve bağımsız değişkenlerle ilgili dokümantasyon gerçek zamanlı olarak görüntülenir.

Şemanın yüklenmesi ve Introspection

Şema, uç noktaya bir GraphQL Introspection isteği aracılığıyla yüklenir. Insomnia şemayı yerel olarak önbelleğe alır ve değişikliklerde otomatik olarak günceller. Yüklemeden sonra otomatik tamamlama (Ctrl+Boşluk), istek doğrulaması ve göndermeden önce olası hataların önizlemesi kullanılabilir hale gelir.

# Insomnia'da değişkenlerle GraphQL sorgusu
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Eklentiler ve özelliklerin genişletilmesi

Insomnia Plugin Hub, istemcinin işlevselliğini genişleten 100'den fazla eklenti içerir. Eklentiler, Preferences → Plugins menüsü aracılığıyla veya npm aracılığıyla manuel olarak kurulur. Popüler kategoriler arasında test verisi üretimi, farklı formatlara dışa aktarma ve özel yanıt doğrulayıcıları yer alır. Her eklenti, genel geliştirici hub'ında yayınlanmadan önce zorunlu moderasyondan geçer.

Popüler eklentiler

• insomnia-plugin-faker — test istekleri için sahte veri (ad, e-posta, telefon) üretimi.
• insomnia-plugin-aws4 — Amazon API Gateway ve S3 ile çalışmak için AWS Signature Version 4 ile istek imzalama.
• insomnia-plugin-utils — isteklerde doğrudan tarihler, karma ve Base64 kodlama ile çalışmak için yardımcı araçlar.

Eklentiler JavaScript ile yazılır ve şablon API'si (response.*, request.*, environment.*) aracılığıyla Insomnia ile etkileşim kurar. Bir eklenti geliştirmek, Node.js hakkında temel bilgi ve insomnia-plugin etiketli bir npm paketi aracılığıyla yayınlama gerektirir.

CLI ve test otomasyonu

Inso CLI, terminalden istekleri ve testleri çalıştırmak için Insomnia'ya yerleşik bir konsol yardımcı programıdır. Inso, tek tek istekleri veya tüm koleksiyonları çalıştırır, sonuçları JSON'a dışa aktarır ve CI/CD boru hatlarına entegre olabilir. inso run collection komutu, bir koleksiyondaki tüm istekleri sırayla yürütür.

GitHub Actions'a entegrasyon örneği

Inso CLI, Docker kapsayıcılarında ve başsız modda çalışır ve bu da GitHub Actions ve GitLab CI'de kullanılmasına olanak tanır. Başlatma yapılandırması, dışa aktarılan koleksiyonun ve ortamın yolunu belirten bir YAML dosyasında açıklanır. JavaScript betikleri aracılığıyla durum kodu ve yanıt gövdesi üzerinde doğrulama (assertion) desteklenir.

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

Insomnia'nın Git ile entegrasyonu ve ekip çalışması

Insomnia, Git aracılığıyla koleksiyon senkronizasyonunu destekler. Koleksiyon dosyaları JSON formatında saklanır ve proje deposuna eklenebilir. Insomnia, değişiklikleri görüntülemek, commit oluşturmak ve birleştirme çakışmalarını doğrudan arayüzden çözmek için yerleşik bir Git istemcisi sağlar.

Git senkronizasyonunun kurulması

Git'i bağlamak için bir depo içeren yerel bir klasör oluşturun ve bunu Insomnia ayarlarında kök dizin olarak belirtin. Uygulama, koleksiyon dosyalarındaki değişiklikleri otomatik olarak izler ve bunları Version Control panelinde görüntüler. Standart işlemler desteklenir: commit, push, pull ve sürümler arasında diff görüntüleme.

Insomnia Cloud ile ekip çalışması

Git olmayan projeler için Insomnia, Insomnia Cloud aracılığıyla bulut senkronizasyonu sunar. Ücretsiz plan, 3'e kadar ekip üyesini ve koleksiyonların otomatik yedeklenmesini içerir. Ücretli planlar; erişim yönetimi, değişiklik denetimi ve öncelikli destek ekler.

Design Mode ve belirtim üretimi

Insomnia'daki Design Mode, OpenAPI 3.0 formatında API belirtimleri oluşturmanıza olanak tanır. Mod, görsel bir düzenleyici gibi çalışır: YAML'ı elle yazmadan uç noktaları ve veri şemalarını tanımlayın. Belirtim JSON veya YAML olarak dışa aktarılabilir.

OpenAPI'den koleksiyon üretimi

Insomnia, OpenAPI belirtimlerini içe aktarır ve her uç nokta için bir istek koleksiyonu oluşturur. Yollar ve şemalar, hazır HTTP isteklerine dönüştürülür. Bu özellik, belirtimin ekibin ayrı bir deposunda saklandığı mikro hizmetlerle entegrasyonda faydalıdır.

İstek etiketleme

Her isteğe renkli bir etiket atanabilir: red, blue, green, orange, purple. Etiketlere göre filtreleme, klasör yapısından bağımsız olarak arama çubuğu aracılığıyla çalışır ve yüzlerce uç nokta ile çok sayıda modüle sahip projelerde gezinmeyi kolaylaştırır.

Design Mode ve belirtim üretimi

Insomnia'daki Design Mode, uygulama içinde doğrudan OpenAPI 3.0 formatında API belirtimleri oluşturmanıza olanak tanır. Mod, görsel bir düzenleyici gibi çalışır: YAML'ı elle yazmadan uç noktaları, veri şemalarını ve parametreleri tanımlayın. Belirtim, depolarda yayınlamak için JSON veya YAML olarak dışa aktarılabilir.

OpenAPI'den koleksiyon üretimi

Insomnia, mevcut OpenAPI belirtimlerini içe aktarır ve her uç nokta için otomatik olarak bir istek koleksiyonu oluşturur. Yollar ve şemalar, doğru veri türleriyle hazır HTTP isteklerine dönüştürülür. Bu özellik, belirtimin ayrı bir arka uç geliştirme ekibi tarafından saklanıp bakımının yapıldığı mikro hizmetlerle entegrasyonda faydalıdır.

İstek etiketleme ve filtreleme

Çok sayıda isteği düzenlemek için Insomnia etiketlemeyi destekler — her isteğe renkli bir etiket atanabilir: red, blue, green, orange, purple. Etiketlere göre filtreleme, klasör yapısından bağımsız olarak arama çubuğu aracılığıyla çalışır ve yüzlerce uç nokta ile çok sayıda işlevsel API modülüne sahip projelerde gezinmeyi kolaylaştırır.