📋
← Rehberlere dön

REST API'lerde JSON Kullanımı: En İyi Uygulamalar

· Etiketler: json, rest-api, api-design, json-best-practices, pagination, web-development

REST API'lerde JSON

JSON ve REST API'ler birbiri için yaratılmıştır. JSON'un hafif sözdizimi, yerel dizi desteği ve evrensel dil desteği, onu modern web API'leri için varsayılan format haline getirir. Ancak API'nizde yalnızca JSON kullanmak yeterli değildir — yerleşik kuralları ve en iyi uygulamaları takip etmek, API'nizin tutarlı, sezgisel ve entegre edilmesi kolay olmasını sağlar.

İstek ve Yanıt Formatı

Tutarlı Zarf Yapısı

Tüm API yanıtları için tutarlı bir JSON zarfı benimseyin. Bu, istemci tarafı işlemeyi öngörülebilir hale getirir ve hata yönetimini basitleştirir.

{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    }
  },
  "meta": {
    "requestId": "req-a1b2c3d4",
    "timestamp": "2026-07-19T10:30:00Z"
  }
}

Snake Case ve Camel Case

Bir adlandırma kuralı seçin ve tüm API'nizde buna bağlı kalın:

  • Camel Case (createdAt, firstName): JavaScript/TypeScript ekosistemlerinde yaygındır
  • Snake Case (created_at, first_name): Python, Ruby ve PHP ekosistemlerinde yaygındır

Hangisini seçerseniz seçin, bunu açıkça belgelendirin ve arka uç diliniz farklı bir kural kullanıyorsa bir dönüşüm katmanı kullanmayı düşünün.

JSON ile HTTP Durum Kodları

Uygun HTTP durum kodları, JSON yanıtlarınızı tamamlar. Bunları tutarlı bir şekilde kullanın:

| Durum Kodu | Anlamı | Ne Zaman Kullanılır | |-------------|---------|-------------| | 200 OK | Başarılı | GET, PUT, PATCH başarısı | | 201 Created | Kaynak oluşturuldu | POST başarısı | | 204 No Content | Silme başarısı | DELETE başarısı (JSON gövdesi yok) | | 400 Bad Request | Geçersiz JSON sözdizimi | Bozuk istek gövdesi | | 401 Unauthorized | Kimlik doğrulama gerekli | Eksik veya geçersiz token | | 403 Forbidden | Yetersiz izinler | Geçerli kimlik doğrulama ancak izin verilmiyor | | 404 Not Found | Kaynak mevcut değil | Geçersiz ID veya yol | | 422 Unprocessable Entity | Doğrulama başarısız | Geçerli JSON'da anlamsal hatalar | | 429 Too Many Requests | Hız sınırı aşıldı | İstemci limitleri aşıyor | | 500 Internal Server Error | Sunucu tarafı hatası | Beklenmeyen hatalar |

Standart Hata Yanıt Formatı

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "İstek gövdesi geçersiz alanlar içeriyor",
    "details": [
      {
        "field": "email",
        "message": "Geçerli bir e-posta adresi olmalıdır",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "age",
        "message": "Pozitif bir tamsayı olmalıdır",
        "code": "OUT_OF_RANGE"
      }
    ]
  }
}

İç İçe Kaynaklar

İlişkileri Temsil Etme

REST API'ler sıklıkla ilişkili kaynakları temsil etmek zorundadır. İşte yaygın desenler:

Gömülü (eager loading):

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customer": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    },
    "items": [
      {
        "productId": 42,
        "name": "Widget",
        "quantity": 2,
        "price": 14.99
      }
    ]
  }
}

Referanslı (lazy loading) — ID'leri kullanın ve ayrı uç noktalar sağlayın:

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customerId": 123,
    "itemIds": [101, 102]
  }
}

Pratik kural: Her zaman birlikte ihtiyaç duyulan ilişkili verileri gömün. Koşullu olarak veya farklı bir zamanda alınan verileri referans olarak verin.

Sayfalama Desenleri

Kaynak listelerini döndürürken sayfalama çok önemlidir. Tutarlı bir sayfalama formatı kullanın:

Ofset Tabanlı Sayfalama

{
  "status": "success",
  "data": [
    { "id": 1, "name": "Kullanıcı 1" },
    { "id": 2, "name": "Kullanıcı 2" }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "totalItems": 156,
    "totalPages": 8,
    "links": {
      "first": "/api/users?page=1&perPage=20",
      "prev": null,
      "next": "/api/users?page=2&perPage=20",
      "last": "/api/users?page=8&perPage=20"
    }
  }
}

İmleç Tabanlı Sayfalama (Büyük Veri Kümeleri İçin Önerilir)

{
  "status": "success",
  "data": [
    { "id": 100, "name": "Kullanıcı 100" },
    { "id": 101, "name": "Kullanıcı 101" }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6MTAxfQ==",
    "hasMore": true
  }
}

İmleç tabanlı sayfalama, yeni kayıtların sayfa sınırlarını kaydırabileceği gerçek zamanlı veriler için daha güvenilirdir.

API İsteklerinde JSON

POST / PUT İstek Gövdeleri

Content-Type: application/json başlığıyla JSON kabul edin:

{
  "title": "Yeni Blog Yazısı",
  "content": "Bu içeriktir...",
  "tags": ["json", "rest-api"],
  "published": false
}

PATCH ile Kısmi Güncellemeler

Kısmi güncellemeler için PATCH kullanın. Yalnızca değişmesi gereken alanları kabul edin:

// PATCH /api/users/123
{
  "email": "yeniemail@example.com"
}

Filtreleme, Sıralama ve Arama

JSON gövdesini temiz tutarak veri işleme için sorgu parametrelerini kullanın:

GET /api/users?filter[role]=admin&sort=-createdAt&search=alice

{
  "status": "success",
  "data": [ /* filtrelenmiş, sıralanmış sonuçlar */ ]
}

Hız Sınırlama

Yanıt başlıklarında ve isteğe bağlı olarak JSON gövdesinde hız sınırı bilgilerini ekleyin:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Çok fazla istek. Lütfen daha sonra tekrar deneyin."
  },
  "meta": {
    "rateLimit": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2026-07-19T11:00:00Z"
    }
  }
}

JSON En İyi Uygulamalar Kontrol Listesi

  • [ ] Tutarlı anahtar adlandırması kullanın (genelinde camelCase veya snake_case)
  • [ ] Her yanıtla birlikte uygun HTTP durum kodlarını döndürün
  • [ ] Makine tarafından okunabilir hata kodlarıyla tutarlı bir hata formatı ekleyin
  • [ ] Liste uç noktalarını standart bir sayfalama nesnesiyle sayfalandırın
  • [ ] İstek/yanıt yapılarını belgelemek ve doğrulamak için JSON Schema kullanın
  • [ ] Tüm JSON uç noktalarında Content-Type: application/json ayarlayın
  • [ ] Üretimde JSON yanıtlarını gzip veya brotli ile sıkıştırın
  • [ ] Maksimum yük boyutu sınırlarını uygulayın (örn. varsayılan 1MB)
  • [ ] JSON verilerini aktarım sırasında şifrelemek için HTTPS kullanın
  • [ ] Dahili bilgileri ifşa etmeden istemcilerin hata ayıklamasına yardımcı olacak şekilde hata ayrıntılarını yapılandırın

API JSON'unuzu Doğrulama

API yanıtlarınızı, biçimlendirme hatalarını istemcilere ulaşmadan önce yakalamak için bir JSON doğrulayıcıdan geçirin. Tutarlı, geçerli JSON yanıtları API'nizi güvenilir ve geliştirici dostu hale getirir. Geliştirme sırasında yüklerinizi test etmek için JSON Formatlayıcı ve Doğrulayıcı aracımızı kullanın.