.http Dosyalarıyla Repo İçinde API Testi: Visual Studio, Rider ve VS Code'da Variable, Environment ve Request Chaining

Sürüm notu: Bu yazıdaki kodlar .NET 10 ile derlenip denenmiştir; .http dosyaları JetBrains HTTP Client CLI 2026.2 (ijhttp, Docker image'ı) ile çalıştırılmış, secret taraması gitleaks 8.30 ile yapılmıştır. Visual Studio ve VS Code REST Client'ın davranışları Microsoft'un ve eklentinin resmi dokümanlarından aktarılmıştır; bu iki editörü bu yazı için çalıştırmadım.

Önce Tahmin Et

Visual Studio'da yazılmış, Visual Studio'da sorunsuz çalışan bir .http dosyası var. İlk istek login, ikincisi token'ı şöyle kullanıyor:

GET {{HostAddress}}/api/auth/me
Authorization: Bearer {{login.response.body.$.accessToken}}

Ekipteki Rider kullanıcısı aynı dosyayı açıp çalıştırıyor. Ne olur: Rider hata verip durur mu, isteği göndermeden uyarır mı, yoksa isteği gönderip bir status code mu alır? Aynı dosya CI'da JetBrains'in ijhttp CLI'ı ile koşarsa build kırmızı mı olur, yeşil mi? Cevap, .http dosyalarının en az bilinen tarafı: aynı uzantı, üç ayrı dialect.

.http Dosyası Nedir, Neden Repo'da Durur?

.http dosyası, HTTP isteklerini neredeyse kablodaki haliyle yazdığın düz bir metin dosyası: request satırı, header'lar, boş satır, body. İstekleri ### ayırır, # ya da // ile başlayan satırlar yorumdur. Format VS Code'un REST Client eklentisiyle yaygınlaştı, JetBrains IDE'leri kendi HTTP Client'ını yıllardır aynı uzantıyla taşıyor, Visual Studio da 17.8'den beri (Microsoft'un dokümanındaki ön koşul) kendi editörüyle destekliyor. ASP.NET Core Web API template'i bu yüzden projenin yanına <Proje>.http dosyası koyar.

İlk yazıdaki matrisin "repo'da yaşar" sütunu en çok bu araca yakışıyor. Dosya API projesinin yanında durur, endpoint değiştiren pull request onu da değiştirir, reviewer ikisini birlikte görür. Bedeli de var: bir dosya, bir IDE'de çalışır; hangi IDE'de, hangi syntax'la yazdığına göre değişir. Bu yazıda Bookstore.Api için iki dosya yazdım: Visual Studio ve VS Code'un ortak syntax'ıyla API projesinin yanında duran src/Bookstore.Api/Bookstore.Api.http, bir de JetBrains dialect'iyle yazılıp CI'da koşabilen tests/http/bookstore-flow.http.

Syntax: Request, Variable ve Dinamik Değerler

Visual Studio ve VS Code REST Client için ortak senaryo:

# Bookstore.Api: login -> kitaplar -> sepet -> sipariş -> siparişi oku
# Visual Studio ve VS Code (REST Client) syntax'ı. Environment: http-client.env.json.
# Şifre commit'lenmeyen .env dosyasından gelir (BOOKSTORE_PASSWORD=...); bkz. .env.example.

# @name login
POST {{HostAddress}}/api/auth/login
Content-Type: application/json

{
  "email": "{{Email}}",
  "password": "{{$dotenv BOOKSTORE_PASSWORD}}"
}

###

# @name books
GET {{HostAddress}}/api/books?page=1&search=Hobbit
Accept: application/json

###

# @name cart
POST {{HostAddress}}/api/carts
Authorization: Bearer {{login.response.body.$.accessToken}}

###

PUT {{HostAddress}}/api/carts/{{cart.response.body.$.id}}/items/{{books.response.body.$.items[0].isbn}}
Authorization: Bearer {{login.response.body.$.accessToken}}
Content-Type: application/json

{
  "quantity": 2
}

###

# @name order
POST {{HostAddress}}/api/orders
Authorization: Bearer {{login.response.body.$.accessToken}}
Content-Type: application/json
X-Request-Id: {{$guid}}

{
  "cartId": "{{cart.response.body.$.id}}",
  "customerName": "Ada Lovelace",
  "customerEmail": "{{Email}}"
}

###

GET {{order.response.headers.Location}}
Authorization: Bearer {{login.response.body.$.accessToken}}

###

Parçalar: {{HostAddress}} ve {{Email}} environment'tan gelen variable'lar. Dosyanın içinde @HostAddress = http://localhost:5080 diye bir satırla da tanımlanabilirdi; Visual Studio'da dosyadaki tanım environment'takini ezer, bu yüzden ortama göre değişecek değerleri dosyaya yazmıyorum. {{$guid}} her istekte yeni bir GUID (128 bit'lik benzersiz kimlik değeri) üretir. Microsoft'un dokümanındaki diğer dinamik değerler {{$randomInt min max}}, {{$datetime iso8601}}, {{$localDatetime rfc1123}} ve {{$timestamp}}; tarihlere -1 d gibi bir offset de verilebiliyor. {{$processEnv BOOKSTORE_PASSWORD}} işletim sisteminin environment variable'ını, {{$dotenv BOOKSTORE_PASSWORD}} da bir .env dosyasındaki değeri okur. Visual Studio .env'i proje klasöründe, REST Client .http dosyasının klasöründe arıyor; dosyayı API projesinin klasörüne koyduğum için ikisinde de aynı yer.

Request Chaining: # @name ve JSONPath

Bir isteğin önüne # @name login yazınca, sonraki istekler onun cevabına {{login.response.body.$.accessToken}} ile ulaşır. Syntax {{name.(response|request).(body|headers).(*|JSONPath|XPath|header-name)}}: body için JSONPath (RFC 9535), header için header'ın adı. Yukarıdaki dosyada üç türü de var: token body'den ($.accessToken), kitabın ISBN'i (uluslararası standart kitap numarası) bir array'in ilk element'inden ($.items[0].isbn), siparişin adresi de header'dan ({{order.response.headers.Location}}).

İki ayrıntı, ikisi de Microsoft'un dokümanında yazıyor. Birincisi, adı verilen isteğin cevabına ulaşabilmek için o isteği önce elle çalıştırmış olman gerekiyor; editör zinciri senin yerine baştan koşmaz. Login'i çalıştırmadan cart'a basarsan header'da çözülmemiş bir ifade kalır. İkincisi, istek birden fazla kez çalıştırıldıysa son cevap kullanılır. Bu, token'ı 15 dakikada bir yenilemek için tek yapman gereken şeyin login'e bir kez daha basmak olduğu anlamına geliyor.

Environment'lar: http-client.env.json, $shared ve Commit'lenmeyen Dosyalar

Visual Studio, .http dosyasının klasöründen başlayıp üst klasörlere doğru ilk http-client.env.json'u arar; editörün sağ üstündeki seçiciden environment seçilir. Bookstore için:

{
  "$shared": {
    "Email": "ada@example.com"
  },
  "dev": {
    "HostAddress": "http://localhost:5080"
  },
  "staff": {
    "HostAddress": "http://localhost:5080",
    "Email": "grace@example.com"
  }
}

$shared bütün environment'lara varsayılan değer verir; staff environment'ı Email'i ezip aynı akışı Grace olarak koşar. Bu dosya commit'lenir ve içinde secret olmaz. Kişisel değerler için yanına http-client.env.json.user konur; aynı environment'ta aynı variable iki dosyada da varsa .user dosyasındaki kazanır.

Visual Studio'nun bir adımı daha var: secret provider'lar. Environment dosyasında bir variable'ın değeri yerine provider verirsin. AspnetUserSecrets değeri projenin user secrets'ından, AzureKeyVault bir Key Vault'tan (Visual Studio'da o vault'a erişimi olan bir hesapla oturum açmış olmak gerekir), Encrypted de Windows'un DPAPI'si (Data Protection API; değeri o makinedeki o kullanıcıya bağlı olarak şifreleyen Windows servisi) ile şifrelenmiş bir değerden okur:

{
  "dev": {
    "Password": {
      "provider": "AspnetUserSecrets",
      "secretName": "Auth:DemoPassword"
    }
  }
}

Ekipçe paylaşılması gereken bir secret için Key Vault en uygunu; user secrets ve DPAPI makineye ve kişiye bağlı kalıyor. Bookstore'da demo şifresi yerel geliştirme için olduğundan basit tutup .env kullandım. Repo'ya yalnız boş bir .env.example giriyor.

VS Code REST Client http-client.env.json'u okumuyor; eklentinin README'si environment'ları VS Code ayarlarında rest-client.environmentVariables altında tanımlıyor, $shared burada da var. Bookstore'un .gitignore'u .vscode/settings.json'u commit'lenebilir bıraktığı için environment'ları oraya koydum:

{
  "rest-client.environmentVariables": {
    "$shared": {
      "Email": "ada@example.com"
    },
    "dev": {
      "HostAddress": "http://localhost:5080"
    },
    "staff": {
      "HostAddress": "http://localhost:5080",
      "Email": "grace@example.com"
    }
  }
}

REST Client'ta istek Ctrl+Alt+R ile gönderilir, environment Ctrl+Alt+E ile değişir. Visual Studio'da isteğin üstündeki Send Request bağlantısına basarsın, environment seçicisine F6 ile gidersin. Visual Studio'nun Endpoints Explorer penceresi (View menüsü, Other Windows) API'nin endpoint'lerini listeler; bir endpoint'e sağ tıklayıp Generate Request dersen proje adını taşıyan .http dosyasına o isteğin iskeleti eklenir. Boş bir dosyaya başlamanın en hızlı yolu bu.

Dialect Farkı: Aynı Dosya JetBrains HTTP Client'ta

Tahmin sorusunun cevabı için yukarıdaki dosyayı değiştirmeden JetBrains'in CLI'ı ijhttp ile koştum. ijhttp, Rider ve IntelliJ'in içindeki HTTP Client motorunun komut satırı sürümü; Docker image'ı olarak geliyor ve Java kurmadan çalışıyor. -D, container içindeki localhost'u host makineye yönlendiriyor; -L VERBOSE gönderilen header ve body'leri basıyor:

$ docker run --rm -v "$PWD:/workdir" jetbrains/intellij-http-client -D -L VERBOSE --no-progress \
    -e dev -v http-client.env.json Bookstore.Api.http \
    | grep -E '^Request|^Authorization|^X-Request-Id|^HTTP/1.1|"password"|completed|^RUN'
Request 'login' POST http://localhost:5080/api/auth/login
  "password": "{{$dotenv BOOKSTORE_PASSWORD}}"
HTTP/1.1 401 Unauthorized
Request 'books' GET http://localhost:5080/api/books?page=1&search=Hobbit
HTTP/1.1 200 OK
Request 'cart' POST http://localhost:5080/api/carts
Authorization: Bearer {{login.response.body.$.accessToken}}
HTTP/1.1 401 Unauthorized
Request '#4' PUT http://localhost:5080/api/carts/{{cart.response.body.$.id}}/items/{{books.response.body.$.items[0].isbn}}
Request 'order' POST http://localhost:5080/api/orders
Authorization: Bearer {{login.response.body.$.accessToken}}
X-Request-Id: {{$guid}}
HTTP/1.1 401 Unauthorized
Request '#6' GET http://{{order.response.headers.Location}}
6 requests completed, 2 have failed tests
RUN FAILED

Yani Rider hata verip durmuyor, istekleri gönderiyor. $dotenv, $guid ve request variable ifadeleri olduğu gibi gidiyor; şifre {{$dotenv BOOKSTORE_PASSWORD}} metni olduğu için login 401 dönüyor, token yerine literal ifade gittiği için sepet ve sipariş de 401. Run'ın kırmızı olmasının sebebi bu 401'ler değil: yalnız URL'si geçersiz kalan iki istek "failed" sayıldı. JetBrains dünyasında 401 almak, bir client.test yazmadığın sürece başarısızlık değildir. Bir de -v http-client.env.json parametresini vermeden önce CLI "Environment files are not set while environment name passed" diyerek hiç başlamadı; Docker içinde environment dosyasını açıkça vermek gerekiyor.

Aynı aracın $shared'ı da tanımadığını gördüm: Email'i $shared'a taşıyınca login, e-posta yerine çözülmemiş bir variable gönderdi ve test düştü. Gözlemlediklerimi ve dokümanlarda yazanları tek tabloda topladım:

Pratik karar şu: Ekip karışık IDE kullanıyorsa ve dosyalar yalnız elle deneme içinse, ortak alt kümede kal: ###, dosya variable'ları ve environment'tan gelen HostAddress. Token'ı da her kullanıcının kendi kişisel environment dosyasına elle koymasını iste. Request chaining'e ve CI'a ihtiyaç varsa ekipçe bir dialect seç ve dosyayı ona göre yaz. Bookstore'da ikisini ayırdım: API projesinin yanındaki dosya Visual Studio ve VS Code kullanıcıları için, tests/http/ altındaki dosya JetBrains dialect'inde ve CI için.

JetBrains Dialect'i: Response Handler, client.test ve ijhttp

JetBrains HTTP Client'ta zincirleme, isteğin altına yazılan JavaScript response handler'ıyla yapılıyor: > {% ... %} bloğu cevabı response object'i olarak görür, client.global.set ile sonraki isteklere değer bırakır, client.test ve client.assert ile assertion yazar. tests/http/bookstore-flow.http'nin başı ve sonu:

# JetBrains HTTP Client için Bookstore akışı (Rider, IntelliJ, ijhttp CLI).
# Şifre: http-client.private.env.json (commit'lenmez) ya da ijhttp -P Password=...

### Login
POST {{HostAddress}}/api/auth/login
Content-Type: application/json

{
  "email": "{{Email}}",
  "password": "{{Password}}"
}

> {%
    client.test("login returns a bearer token", () => {
        client.assert(response.status === 200, "status " + response.status);
        client.assert(response.body.tokenType === "Bearer", "tokenType " + response.body.tokenType);
    });
    client.global.set("token", response.body.accessToken);
%}

### Books
GET {{HostAddress}}/api/books?page=1&search=Hobbit
Accept: application/json

> {%
    client.test("The Hobbit is in the catalog", () => {
        client.assert(response.body.items.length === 1, "items " + response.body.items.length);
    });
    client.global.set("isbn", response.body.items[0].isbn);
%}

### Place order
POST {{HostAddress}}/api/orders
Authorization: Bearer {{token}}
Content-Type: application/json
X-Request-Id: {{$uuid}}

{
  "cartId": "{{cartId}}",
  "customerName": "Ada Lovelace",
  "customerEmail": "{{Email}}"
}

> {%
    client.test("order is created with a Location", () => {
        client.assert(response.status === 201, "status " + response.status);
        client.assert(response.headers.valueOf("Location") !== null, "no Location header");
    });
    client.global.set("orderUrl", response.headers.valueOf("Location"));
%}

Aradaki sepet istekleri aynı kalıpta; dosyanın tamamı repo'da. Şifre http-client.private.env.json'da duruyor. JetBrains'in dokümanı bu dosyanın değerlerinin public dosyadakileri ezdiğini söylüyor ama aynı sayfanın başka bir yerinde tersini yazıyor. Denedim: public dosyaya yanlış, private dosyaya doğru şifre koyunca ijhttp 2026.2'de private kazandı ve akış geçti. Koşu ve JUnit raporu:

$ docker run --rm -v "$PWD:/workdir" jetbrains/intellij-http-client -D --no-progress \
    -e dev -v http-client.env.json -p http-client.private.env.json bookstore-flow.http --report
Request 'Login' POST http://localhost:5080/api/auth/login
Request 'Books' GET http://localhost:5080/api/books?page=1&search=Hobbit
Request 'Create cart' POST http://localhost:5080/api/carts
Request 'Add two copies' PUT http://localhost:5080/api/carts/01a1d955-33a7-7440-8fd7-55be56d8931c/items/9780261102217
Request 'Place order' POST http://localhost:5080/api/orders
Request 'Read order' GET http://localhost:5080/api/orders/5

6 requests completed, 0 have failed tests
RUN SUCCESSFUL
$ head -6 reports/report.xml
<?xml version="1.0" encoding="UTF-8"?>
<testsuites tests="18" name="IntelliJ IDEA HTTP Client">
  <testsuite tests="18" name="bookstore-flow" failures="0" errors="0" skip="0">
    <testcase classname="http.Login" name="Response" time="0.656" />
    <testcase classname="http.Login" name="login returns a bearer token" time="0.006" />
    <testcase classname="http.Login" name="Response Handler" time="1.282" />

--report'u dosya adından sonra yazmak gerekiyor; önce yazınca değer alabilen bir seçenek olduğu için dosya adını rapor klasörü sanıyor ve "Missing required parameter: 'files'" diye duruyor. Şifreyi yanlış verip (-P Password=wrong) koşunca çıkış kodu 1 oldu ve hata zinciri okunur kaldı:

Request 'Login' POST http://localhost:5080/api/auth/login
Failed bookstore-flow.http#0 login returns a bearer token

AssertionError: status 401
  this.assert (at js-graalvm-response-handler.js:45)
  :=> (at /workdir/bookstore-flow.http:15)
Request 'Books' GET http://localhost:5080/api/books?page=1&search=Hobbit
Request 'Create cart' POST http://localhost:5080/api/carts
Failed bookstore-flow.http#2 cart is created
...
6 requests completed, 5 have failed tests
RUN FAILED

Zincirin ortasında token boş kalınca sonraki isteklerin URL'leri {{cartId}} gibi çözülmemiş variable'larla kaldı ve CLI her biri için uzun bir Java stack trace bastı. Rapor için sorun değil, ama loglarda ilk "Failed" satırını aramak gerektiğini bil. CI'da şifreyi -P ile vermek, komut satırına ve process listesine düşürür; pipeline'ın secret'ından http-client.private.env.json dosyasını oluşturmak daha temiz.

.gitignore: Hangi Dosya Kendiliğinden Korunuyor?

Bookstore'un .gitignore'u dotnet new gitignore template'inden geliyor. Üç secret dosyasını git check-ignore ile sordum:

$ git check-ignore -v src/Bookstore.Api/.env src/Bookstore.Api/http-client.env.json.user tests/http/http-client.private.env.json
.gitignore:7:.env	src/Bookstore.Api/.env
.gitignore:12:*.user	src/Bookstore.Api/http-client.env.json.user

İlk ikisi korunuyor: template'in güncel hali .env'i ve *.user'ı içeriyor. Üçüncüsü listede yok, yani http-client.private.env.json commit'lenebilir durumda. JetBrains'in dokümanı da Rider'ın bu dosyayı kendi Git entegrasyonunda takip etmediğini ama .gitignore'a eklemediğini yazıyor; terminalden git add . yapan biri onu commit'ler. Bookstore'a şu satırları ekledim:

# HTTP client secret'ları ve raporları (Rider / ijhttp)
http-client.private.env.json
tests/http/reports/

Microsoft'un dokümanı da .env dosyalarının varsayılan olarak ignore edilmeyebileceği konusunda uyarıyor. Eski bir template'ten gelen .gitignore'da .env satırı olmayabilir; kendi repo'nda aynı komutla kontrol et.

Üretimde Dikkat

.http dosyasındaki environment listesine production'ı koyma. Seçici bir tık uzakta; staff environment'ında Grace'in yetkisiyle çalışan bir PUT isteğini yanlışlıkla production'a göndermek kolay. Staging gerekiyorsa adı bağırsın (staging-readonly) ve yalnız GET istekleri olan ayrı bir dosyayla kullan.

CI'da ijhttp ile koşacaksan API'nin ayağa kalkmasını bekle. ijhttp'nin kendi retry'ı yok; API henüz dinlemiyorsa ilk istek bağlantı hatasıyla düşer. İkinci yazıdaki curl --retry-connrefused satırı bekleme adımı olarak işe yarıyor; beşinci yazıda Bruno için aynı düzeni GitHub Actions'ta kuracağız. Docker image'ının latest etiketi her JetBrains sürümüyle değişir; CI'da bir sürüme sabitle ki dialect davranışı bir sabah sessizce değişmesin.

Response handler'lar JavaScript çalıştırıyor. Rider'da başkasının yazdığı bir .http dosyasını çalıştırmak, onun script'ini senin makinende çalıştırmak demek. Repo'na dışarıdan gelen pull request'lerdeki .http değişikliklerini kod gibi incele.

Sık Düşülen Tuzaklar

Token'ı dosyaya yazmak. @token = eyJ... satırı en kısa yol gibi görünür. Denemek için bir repo'da öyle bir dosya commit'leyip gitleaks ile taradım:

$ gitleaks git --no-banner --redact -v --no-color .
Finding:     REDACTED
Secret:      REDACTED
RuleID:      jwt
Entropy:     5.576108
File:        quick.http
Line:        2
Commit:      1f9636f8fc96981864ead5f7416dda53d5d3c294
Author:      demo
Email:       demo@example.com
Date:        2026-11-14T09:10:44Z
Fingerprint: 1f9636f8fc96981864ead5f7416dda53d5d3c294:quick.http:jwt:2

12:13PM INF 1 commits scanned.
12:13PM INF scanned ~447 bytes (447 bytes) in 94.6ms
12:13PM WRN leaks found: 1

Token süresi dolmuş olsa bile içindeki bilgiler okunur; pre-commit hook'ta ya da CI'da bir secret tarayıcısı çalıştır ve token'ı her zaman environment'tan ya da login isteğinden al.

Dosyadaki @HostAddress satırını unutmak. Visual Studio'da dosyada tanımlı variable environment dosyasındakini ezer; seçicide staging'i seçtiğini sanırken istekler hâlâ dosyadaki adrese gider.

Zinciri baştan koşmadan ortadaki isteğe basmak. Visual Studio ve REST Client'ta adı verilen isteğin cevabı ancak o istek çalıştırıldıysa var; eski bir token'la gelen 401'i API hatası sanma.

Dialect'leri bir dosyada karıştırmak. Visual Studio dosyasına > {% %} bloğu eklemek ya da JetBrains dosyasında $dotenv kullanmak, dosyayı her iki taraf için yarı çalışır hale getirir; yukarıdaki koşuda gördüğümüz gibi bu çoğu zaman hata değil, sessiz bir 401 olarak görünür.

Küçük Bir Deneme

★☆☆ Visual Studio'da Bookstore.Api projesinde Endpoints Explorer'ı aç, GET /api/books/{isbn} için Generate Request de ve oluşan isteği {{HostAddress}} ile çalışacak şekilde düzenle. Rider kullanıyorsan aynı isteği elle yaz ve staff environment'ında çalıştır.

★★☆ bookstore-flow.http'ye Grace olarak kapak yükleyen bir istek ekle. JetBrains HTTP Client'ta multipart body'yi < ./the-hobbit.png ile dosyadan okuyabilirsin. Response handler'da status'un 200 olduğunu ve contentType'ın image/png geldiğini test et, sonra Ada'nın token'ıyla 403 aldığını doğrulayan ikinci bir test yaz.

★★★ Ekibin karışık IDE kullanıyor. Bookstore.Api.http'den request chaining'i kaldırıp yalnız ortak alt kümeyle (dosya variable'ları, environment, elle girilen token) yaz ve aynı dosyayı ijhttp ile koşarak bütün isteklerin çözüldüğünü doğrula. Neyi kaybettiğini ve bunun ekip için kabul edilebilir olup olmadığını iki cümleyle yaz.

.http dosyaları repo'da yaşıyor ama dialect'e bağlı ve ekip dışındaki biriyle paylaşmak zor. Bir sonraki yazıda bu soruna en yaygın cevabı inceliyoruz: Postman'de collection, environment, variable scope'ları, script'ler, mock server ve CLI.