JSON API Yanıtını Biçimlendir: Güzel Çıktı Örneği

Biçimlendirilmiş Yanıt

Küçültülmüş girdiye bir biçimlendirici uygulamak şunu üretir:

{
  "status": "success",
  "data": {
    "users": [
      {
        "id": 1,
        "name": "Alice Chen",
        "email": "alice@example.com",
        "role": "admin",
        "created_at": "2024-01-15T08:30:00Z"
      },
      {
        "id": 2,
        "name": "Bob Martinez",
        "email": "bob@example.com",
        "role": "editor",
        "created_at": "2024-03-22T14:15:00Z"
      },
      {
        "id": 3,
        "name": "Carol Williams",
        "email": "carol@example.com",
        "role": "viewer",
        "created_at": "2024-06-10T11:45:00Z"
      }
    ],
    "total": 3,
    "page": 1,
    "per_page": 25
  },
  "meta": {
    "request_id": "req_abc123",
    "response_time_ms": 42
  }
}

Yapı hemen okunabilir: sayfalanmış bir kullanıcı listesi artı istek meta verilerini saran bir başarı zarfı.

Biçimlendirilmiş JSON Hata Ayıklama İçin Neden Önemlidir

Bir API’yi curl’ladığınızda ve bir duvar küçültülmüş JSON aldığınızda yaptığınız ilk şey, onu bir biçimlendiriciden geçirmektir. Nedeni pratiktir: iç içe yapılar tek bir satırda görünmez. Girinti olmadan eksik bir anahtarı tarayamaz, null değeri fark edemez veya dizi uzunluğunu doğrulayamazsınız.

Biçimlendirilmiş JSON, birkaç hata ayıklama görevini çok daha hızlı hale getirir:

• Beklenmeyen null veya eksik alanları bulma. Her anahtar kendi satırındayken, eksik bir alan uzun bir stringin içinde saklanmak yerine hemen göze çarpar.
• İç içe geçmeyi doğrulama. Küçültülmüş formda derinlemesine iç içe JSON, manuel olarak parantez ve köşeli parantez saymayı gerektirir. Girinti, ağaç yapısını anında görünür kılar.
• Yanıtları diff’leme. İki küçültülmüş JSON blob’u, yalnızca bir alan değişmiş olsa bile tek bir değiştirilmiş satır olarak diff’lenir. Güzel biçimlendirilmiş JSON temiz bir şekilde diff’lenir ve tam olarak hangi alanın değiştiğini gösterir.
• Kod incelemesinde okuma. Sürüm kontrolüne gönderilen JSON test fixture’ları, diff’lerin incelenebilir olması için her zaman güzel biçimlendirilmelidir.

Yaygın REST API Yanıt Yapıları

Yukarıdaki örnek, yaygın olarak kullanılan bir deseni izler: gerçek yükü içeren bir veri nesnesi ve istek düzeyinde bilgi içeren bir meta nesne ile üst düzey bir durum alanı. Bu desenin varyasyonları sürekli karşımıza çıkar:

JSend tarzı zarf

{
  "status": "success",
  "data": { ... }
}

JSON:API zarfı

{
  "data": [ ... ],
  "links": { "next": "...", "self": "..." },
  "meta": { "total": 42 }
}

Hata yanıtı

{
  "status": "error",
  "code": "RESOURCE_NOT_FOUND",
  "message": "User 99 does not exist",
  "request_id": "req_xyz789"
}

Bunlardan herhangi birini biçimlendirmek, zarf yapısını hemen belirgin hale getirir; bu, bir istemci yazarken ve istediğiniz veriye ulaşmak için hangi yolu izlemeniz gerektiğini anlamanız gerektiğinde yardımcı olur.

Girinti Kuralları

Baskın iki seçenek 2 boşluk ve 4 boşluktur. Sekmeler de geçerli JSON boşluğudur ancak paylaşılan yapılandırmada daha az yaygındır.

2 boşluk, birçok JavaScript aracında varsayılandır. JSON.stringify(obj, null, 2) ve jq her ikisi de 2 boşluklu çıktı üretir. İç içe yapıları kompakt tutar; bu, rutin olarak derinlemesine iç içe JSON ile çalışıyorsanız önemlidir.

4 boşluk Python kuralıdır. json.dumps(obj, indent=4) bulacağınız en yaygın Python snippet’idir. Ayrıca birçok IDE biçimlendiricisinde varsayılandır.

Ekibinizin zaten kullandığına göre seçin. Bir .editorconfig veya proje düzeyinde Prettier yapılandırmanız varsa, girinti boyutunu zaten belirtiyordur. Bunu kullanın. Aynı dosyada veya aynı depoda girinti genişliklerini karıştırmayın.

Komut Satırında JSON Biçimlendirme

jq, komut satırı JSON biçimlendirme ve sorgulama için standart araçtır. Bir kez kurun (brew install jq veya apt install jq) ve sürekli kullanacaksınız.

Ham bir string’i biçimlendirme:

echo '{"name":"Alice","role":"admin"}' | jq .

Bir dosyayı biçimlendirme:

jq . response.json

Bir curl yanıtını satır içi biçimlendirme:

curl -s https://api.example.com/users | jq .

Yanıtı biçimlendirirken iç içe bir değer çıkarma:

curl -s https://api.example.com/users | jq '.data.users[0].email'

jq mevcut değilse, Python’un standart kütüphanesi temel durumu kapsar:

echo '{"name":"Alice"}' | python3 -m json.tool

Ya da Node.js kullanarak:

node -e "let d=''; process.stdin.on('data', c => d+=c); process.stdin.on('end', () => console.log(JSON.stringify(JSON.parse(d), null, 2)))" <<< '{"name":"Alice"}'

Bu ayrıntılı. jq kullanın.

Üretim İçin Küçültme

Küçültülmüş JSON sunmak yük boyutunu azaltır, ancak etkisi bağlama bağlıdır:

Küçültme hakkında endişelenmeden önce HTTP sıkıştırmasını (Content-Encoding: gzip veya br) etkinleştirin. Boşluk son derece iyi sıkışır. Gzip, tekrarlayan girintiyi neredeyse sıfıra sıkıştırır. API yanıtlarınızı zaten sıkıştırıyorsanız, JSON küçültmenin ek adımı azalan getiriler üretir.

Küçültmenin açıkça yardımcı olduğu yerler: tutarlı sıkıştırma olmadan sunulan büyük statik JSON varlıkları. Çeviri dosyaları, GeoJSON veri kümeleri ve paketlenmiş yapılandırma dosyaları iyi adaylardır.

Biçimlendirirken JSON Doğrulama

JSON’u yeniden yaymadan önce ayrıştıran bir biçimlendirici, girdiyi de doğrular. JSON’ınızda bir sözdizimi hatası varsa (sonda virgül, tırnaksız anahtar, eksik parantez), biçimlendirici bunu yakalar ve ayrıştırmanın nerede başarısız olduğunu gösterir. Bu, kod dağıtmak ve çalışma zamanı JSON ayrıştırma hatasını beklemekten daha hızlı bir geri bildirim döngüsüdür.

Yaygın JSON sözdizimi hataları:

• Bir nesnedeki son anahtardan veya bir dizideki son öğeden sonra sonda virgül. JavaScript nesne literal’lerinde geçerlidir ancak JSON’da değildir.
• Tek tırnaklı stringler. JSON her yerde çift tırnak gerektirir.
• Tırnaksız anahtarlar. {name: "Alice"} JavaScript’tir, JSON değildir.
• Yorumlar. JSON’da yorum sözdizimi yoktur. // veya /* */ ayrıştırma hatasına neden olur.

Yorumlar ve sonda virgüller içeren JSON benzeri bir formata ihtiyacınız varsa JSON5 veya JSONC’ye bakın, ancak standart JSON ayrıştırıcılarının bunları reddedeceğini unutmayın.