Sayfa yükleniyor

Destek Müşteri Girişi Sepet (0)

Ders 94 – REST JSON API yanıtı

REST tabanlı JSON API’lerinde doğru Content‑Type, HTTP durum kodları ve json_encode kullanımıyla tutarlı yanıtlar üretmeyi adım adım öğrenin.

Ders 94 – REST JSON API yanıtı

Web uygulamaları günümüzde sadece HTML sayfaları sunmakla kalmıyor, aynı zamanda mobil ve tek‑sayfa uygulamaları için veri servisleri de sağlıyor. Bu servislerin en yaygın biçimi JSON tabanlı REST API’leridir. Yanıtların doğru bir biçimde oluşturulması, istemcilerin hatasız çalışması ve API’nin bakımının kolay olması açısından kritik bir adımdır. Bu derste, PHP ile Content‑Type başlığını ayarlamaktan, uygun HTTP durum kodlarını göndermeye, json_encode fonksiyonunu güvenli bir şekilde kullanmaya ve hata mesajlarını tutarlı bir şemada döndürmeye kadar tüm süreci adım adım inceleyeceğiz.

Temeller

REST (Representational State Transfer) mimarisi, istemci‑sunucu iletişimini standart HTTP metodları (GET, POST, PUT, DELETE vb.) ve durum kodları üzerinden tanımlar. JSON (JavaScript Object Notation) ise hafif, insan‑okunur ve makine‑çözümlemeli bir veri formatıdır. Bir API yanıtı üç temel unsurdan oluşur:

  • Başlıklar (Headers): Content-Type gibi yanıtın ne tür veri içerdiğini belirtir.
  • Durum Kodu (Status Code): 200, 201, 400, 404, 500 gibi istemcinin isteğinin sonucunu gösterir.
  • Gövde (Body): JSON formatında gerçek veri ya da hata mesajı.

PHP’de bu unsurları kontrol etmek oldukça basittir; header() fonksiyonu başlık eklemek, http_response_code() fonksiyonu durum kodu ayarlamak ve json_encode() fonksiyonu veri dizisini JSON’a dönüştürmek için kullanılır.

Adım adım API yanıtı hazırlama

Aşağıdaki adımları takip ederek tutarlı bir JSON API yanıtı oluşturabilirsiniz:

  1. İçerik tipini ayarlayın: header('Content-Type: application/json; charset=utf-8'); ifadesi, istemciye yanıtın JSON olduğunu bildirir.
  2. Durum kodunu belirleyin: İsteğin başarılı olup olmadığını http_response_code() ile tanımlayın. Başarılı bir GET isteği için 200, yeni bir kaynak oluşturulduysa 201, hatalı bir istek için 400‑499, sunucu hatası için 500‑599 kodları kullanılmalıdır.
  3. Veriyi hazırlayın: Yanıt gövdesi bir dizi (array) olmalı ve en az iki anahtar içermelidir: success (boolean) ve data (gerçek veri) ya da error (hata mesajı). Bu şema, istemcinin yanıtı tek bir noktadan analiz etmesini sağlar.
  4. JSON’a dönüştürün: json_encode() fonksiyonunu JSON_UNESCAPED_UNICODE ve JSON_PRETTY_PRINT bayraklarıyla çağırarak okunabilir bir çıktı elde edin.
  5. Çıkışı gönderin ve scripti sonlandırın: echo ile JSON stringini yazdırın ve exit; ile scripti bitirin. Bu, olası ek çıktının (ör. PHP uyarıları) yanıt gövdesine karışmasını önler.

Aşağıdaki kod bloğu, bu adımları bir fonksiyon içinde toplayarak tekrar kullanılabilir bir yapı sunar.

Örnek kod

<?php
function jsonResponse(array $payload, int $statusCode = 200): void {
    // 1. Content‑Type başlığını ayarla
    header('Content-Type: application/json; charset=utf-8');
    // 2. HTTP durum kodunu belirle
    http_response_code($statusCode);
    // 3. JSON’a dönüştür ve çıktıyı gönder
    $options = JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT;
    echo json_encode($payload, $options);
    // 4. Scripti sonlandır
    exit;
}

// Başarılı bir GET isteği örneği
if ($_SERVER['REQUEST_METHOD'] === 'GET') {
    $data = [
        'id' => 42,
        'ad' => 'Murat Soft',
        'email' => 'info@muratsoft.com'
    ];
    $payload = [
        'success' => true,
        'data' => $data
    ];
    jsonResponse($payload, 200);
}

// POST ile yeni bir kullanıcı ekleme örneği
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $input = json_decode(file_get_contents('php://input'), true);
    if (empty($input['ad']) || empty($input['email'])) {
        $payload = [
            'success' => false,
            'error' => [
                'code' => 'VALIDATION_ERROR',
                'message' => 'Ad ve email alanları zorunludur.'
            ]
        ];
        jsonResponse($payload, 400);
    }
    // Kayıt başarılı varsayalım
    $payload = [
        'success' => true,
        'data' => ['id' => 101] // yeni oluşturulan kaydın ID'si
    ];
    jsonResponse($payload, 201);
}
?>

Yukarıdaki örnek iki temel senaryoyu kapsar: GET isteğiyle veri okuma ve POST isteğiyle veri oluşturma. Hata durumunda tutarlı bir error nesnesi döndürülür, böylece istemci hatayı kolayca ayrıştırabilir.

Sık karşılaşılan hatalar

  • Başlıkların eksik veya hatalı gönderilmesi: Content-Type ayarlanmamışsa tarayıcı yanıtı HTML olarak yorumlayabilir ve JSON ayrıştırma hatası verir.
  • Yanlış durum kodu: Başarısız bir istekte 200 dönmek, istemcinin hatayı görmezden gelmesine yol açar. Her durum için uygun kodu seçmek API’nin güvenilirliğini artırır.
  • json_encode hataları: UTF‑8 dışı karakterler, döngüsel referanslar veya çok büyük veri setleri json_encode() fonksiyonunun false döndürmesine neden olabilir. json_last_error_msg() ile hatayı yakalayın.
  • Gereksiz uyarı ve notice mesajları: PHP’nin display_errors ayarı açık olduğunda, hata mesajları JSON gövdesine karışır ve istemciyi bozar. Üretim ortamında display_errors kapalı olmalı.

Özet

Bu derste, PHP ile REST JSON API yanıtı oluşturmanın tüm aşamalarını ele aldık. Doğru Content‑Type başlığı, uygun HTTP durum kodu ve tutarlı JSON şeması, API’nizin kullanılabilirliğini ve bakımını büyük ölçüde iyileştirir. jsonResponse() gibi bir yardımcı fonksiyon, kod tekrarını azaltır ve her endpoint’te aynı standartları uygulamayı garantiler. Üretim ortamına geçmeden önce kontrol listesini gözden geçirin ve hataları loglayıp kullanıcıya sadece güvenli mesajlar gönderdiğinizden emin olun.

  • Başlık Content-Type: application/json gönderildi mi?
  • Durum kodu isteğin sonucunu doğru yansıtıyor mu?
  • JSON geçerli mi? json_last_error() ile kontrol edin.
  • Hata mesajları kullanıcıya doğrudan gösterilmiyor mu?

SSS

Soru 1: JSON yanıtında null değerler neden sorun yaratabilir?
Yanıt: null değerler, istemcinin tip kontrolü yapmasını zorlaştırır. Özellikle data alanı beklenen bir nesne ise null yerine boş bir dizi ([]) döndürmek daha güvenlidir.

Soru 2: UTF‑8 olmayan karakterler json_encode hatası verir mi?
Yanıt: Evet. PHP 5.4 ve üzeri JSON_UNESCAPED_UNICODE bayrağıyla UTF‑8 dışı karakterleri kaçırmaya çalışır, ancak karakter seti doğru ayarlanmamışsa json_last_error_msg() “Malformed UTF-8 characters” hatasını verir. Veri tabanından gelen tüm metinleri utf8_encode() ya da mb_convert_encoding() ile UTF‑8’e dönüştürün.

Soru 3: API’de her zaman pretty print kullanmalı mıyım?
Yanıt: Geliştirme ortamında okunabilirliği artırır, ancak üretim ortamında ekstra byte maliyeti yaratır. JSON_PRETTY_PRINT bayrağını sadece APP_DEBUG aktifken ekleyin.

Paylaş

Yorumlar

Henüz onaylanmış yorum yok. İlk yorumu siz yazın.

Yorum yaz

Yorumunuz yönetici onayından sonra yayınlanır.

İlgili yazılar

Ders 100 – İleri yol haritası

PHP serisinin son dersinde ileri seviye konular, framework seçimi, Composer ekosistemi, mikro pro…

Ders 99 – Güvenli yapılandırma kontrol listesi

Üretim ortamı için PHP yapılandırma ayarlarını adım adım kontrol eden, hatasız ve güvenli bir yap…

Ders 98 – OpCache ve performans ipuçları

OpCache'ın çalışma prensibi, yapılandırma adımları ve gerçek dünyada performans artırmak için pra…

Ders 97 – Fibers’a kısa bakış (PHP 8.1)

PHP 8.1 ile gelen Fibers özelliğini adım adım öğrenin, kooperatif concurrency kavramını kavrayın …

Demo
Büyütülmüş Görsel