Wordpress İle Özel Rest Api Uç Noktası Nasıl Yapılır?

Ön Hazırlık ve Gereksinimler

Özel bir REST API uç noktası oluşturmadan önce çalışma ortamınızın hazır olduğundan emin olmalısınız. WordPress REST API, 4.7 sürümünden beri çekirdek yapının bir parçasıdır. Geliştirme sürecinde aşağıdaki araçlara sahip olmanız işinizi kolaylaştıracaktır:

• WordPress 6.x veya üzeri: Güncel sürüm, güvenlik ve performans iyileştirmeleri için zorunludur.
• PHP 8.2 veya üzeri: Modern sözdizimi ve tip güvenliği için önerilen sürümdür.
• Postman veya Insomnia: Oluşturduğunuz uç noktaları test etmek için kullanacağınız API istemcileri.
• WP_DEBUG: Geliştirme aşamasında hataları anlık görmek için wp-config.php dosyanızda define('WP_DEBUG', true); modunu açık tutun.

WordPress REST API Yapısını Anlamak

WordPress REST API, HTTP metodlarını (GET, POST, PUT, DELETE) kullanarak verilerle etkileşime girmenizi sağlar. Özel bir uç nokta oluşturmak için register_rest_route() fonksiyonunu kullanırız. Bu fonksiyon, rotanın adını, metodunu ve veriyi döndürecek olan geri çağırma (callback) fonksiyonunu tanımlar.

Aşağıdaki temel örnek, basit bir "Merhaba Dünya" uç noktası oluşturur:

add_action('rest_api_init', function () {
    register_rest_route('ozel-api/v1', '/selam', array(
        'methods' => 'GET',
        'callback' => 'ozel_api_selam_mesaji',
    ));
});

function ozel_api_selam_mesaji() {
    return new WP_REST_Response(array('mesaj' => 'Merhaba, WordPress API dünyasına hoş geldiniz!'), 200);
}

Bu kod bloğu, /wp-json/ozel-api/v1/selam adresine bir GET isteği attığınızda JSON formatında bir mesaj döndürür. register_rest_route fonksiyonu, API'nizin namespace (isim alanı) ve route (rota) yapısını belirler.

Adım Adım Özel Veri Sorgulama

Sadece statik mesajlar döndürmek nadiren yeterlidir. Genellikle veritabanından özel veriler çekmek istersiniz. Örneğin, belirli bir kategoriye ait ürünleri veya özel bir veritabanı tablosundaki kayıtları çekmek için callback fonksiyonu içinde WP_Query veya $wpdb kullanabilirsiniz.

function ozel_api_son_yazilari_getir(WP_REST_Request $request) {
    $args = array(
        'post_type' => 'post',
        'posts_per_page' => 5,
    );
    $query = new WP_Query($args);
    $yazilar = $query->posts;

    if (empty($yazilar)) {
        return new WP_Error('yazi_bulunamadi', 'Hiç yazı bulunamadı', array('status' => 404));
    }

    return rest_ensure_response($yazilar);
}

Bu fonksiyon, WordPress'in standart postlarını çeker ve rest_ensure_response ile API formatına uygun hale getirir. Eğer veri bulunamazsa, WP_Error sınıfı ile anlamlı bir hata mesajı döndürmek, API'nizin hata yönetimi kalitesini artırır.

Güvenlik: Yetkilendirme ve Doğrulama

Kritik Uyarı: API uç noktalarınızda hassas veriler (kullanıcı bilgileri, özel ayarlar vb.) paylaşıyorsanız mutlaka yetkilendirme (authorization) kullanın. Herkese açık uç noktalar, veritabanı sızıntılarına yol açabilir. permission_callback parametresini boş bırakmayın.

Bir uç noktayı sadece giriş yapmış yöneticilerin görmesini sağlamak için current_user_can() fonksiyonunu kullanmalısınız:

register_rest_route('ozel-api/v1', '/admin-ozel', array(
    'methods' => 'GET',
    'callback' => 'admin_sadece_verisi',
    'permission_callback' => function () {
        return current_user_can('edit_posts');
    }
));

Bu yapı, isteği yapan kullanıcının yetkisi yoksa API'nin otomatik olarak 401 Unauthorized hatası döndürmesini sağlar.

Girdi Doğrulama ve SQL Injection Koruması

Kullanıcıdan parametre alırken (örneğin /ozel-api/v1/yazi?id=1), gelen veriyi mutlaka temizlemeli ve doğrulamalısınız. args parametresi ile gelen verinin tipini belirleyebilirsiniz.

register_rest_route('ozel-api/v1', '/yazi', array(
    'methods' => 'GET',
    'callback' => 'yazi_detay_getir',
    'args' => array(
        'id' => array(
            'validate_callback' => function($param, $request, $key) {
                return is_numeric($param);
            }
        ),
    ),
));

Veritabanı işlemlerinde ise asla doğrudan SQL sorgusu yazmayın. Her zaman $wpdb->prepare() metodunu kullanarak SQL Injection saldırılarına karşı önlem alın.

Yöntem Karşılaştırması

Sıkça Sorulan Sorular

API uç noktam neden 404 hatası veriyor?

Genellikle kalıcı bağlantı ayarlarının (permalink) güncellenmemesinden kaynaklanır. Ayarlar > Kalıcı Bağlantılar sayfasına gidip "Değişiklikleri Kaydet" butonuna basarak .htaccess dosyasını yenileyin.

JSON yanıtını nasıl özelleştirebilirim?

Callback fonksiyonunuzda veriyi bir dizi (array) olarak oluşturun. WP_REST_Response sınıfı bu diziyi otomatik olarak JSON formatına dönüştürecektir.

API'yi nasıl test ederim?

Postman uygulamasını indirin, sitenizin URL'sini ve oluşturduğunuz rotayı girin. GET isteği atarak yanıtı inceleyin.

POST isteklerinde veri nasıl gönderilir?

İstek gövdesinde (body) JSON formatında veri gönderin. WordPress tarafında $request->get_json_params() ile bu verilere erişebilirsiniz.

Performans için ne yapmalıyım?

Çok sık çağrılan uç noktalarda wp_cache_set veya transient API kullanarak verileri önbelleğe almayı ihmal etmeyin.

Yasal Sorumluluk Reddi: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Üretim ortamında (production) kullanmadan önce mutlaka güvenlik testlerinden geçirin ve kodların sitenizin genel performansı üzerindeki etkisini izleyin.

API Yanıtlarını Hızlandırmak İçin Transient API Kullanımı

Özel uç noktalarınızda karmaşık veritabanı sorguları veya ağır hesaplamalar yapıyorsanız, her istekte bu süreci tekrarlamak sunucu kaynaklarını tüketir. WordPress'in Transient API'si, verileri belirli bir süre boyunca veritabanında saklayarak API yanıt süresini milisaniyelere indirebilir.

function get_cached_custom_data() {
    $transient_key = 'my_custom_api_data';
    $data = get_transient($transient_key);

    if (false === $data) {
        // Veriyi ağır bir sorgu ile çekiyoruz
        $data = get_posts(array('post_type' => 'product', 'posts_per_page' => 50));
        
        // Veriyi 1 saatliğine önbelleğe al
        set_transient($transient_key, $data, HOUR_IN_SECONDS);
    }

    return $data;
}

Gelişmiş Hata Ayıklama ve Loglama Teknikleri

API uç noktalarınızda beklenmedik hatalar oluştuğunda, kullanıcıya sadece "500 Internal Server Error" döndürmek yerine, geliştirici dostu hata mesajları sunmak hata ayıklama sürecini hızlandırır. WP_REST_Response nesnesini kullanarak hata durumlarını özelleştirebilirsiniz.

Hata Yönetimi İçin İpucu

API yanıtlarınızda WP_Error sınıfını kullanarak, istemci tarafına hatanın nedenini net bir şekilde bildirebilirsiniz. Aşağıdaki örnek, yetkisiz erişim veya eksik parametre durumunda nasıl bir yapı kurulması gerektiğini gösterir:

function my_custom_endpoint_handler($request) {
    $id = $request->get_param('id');

    if (empty($id)) {
        return new WP_Error(
            'missing_id', 
            'Lütfen geçerli bir ID parametresi gönderin.', 
            array('status' => 400)
        );
    }

    $post = get_post($id);

    if (!$post) {
        return new WP_Error(
            'post_not_found', 
            'Belirtilen ID ile eşleşen içerik bulunamadı.', 
            array('status' => 404)
        );
    }

    return rest_ensure_response($post);
}

API Sürümleme (Versioning) Stratejisi

API'niz zamanla geliştikçe, mevcut uç noktalarınızda yapacağınız değişiklikler mevcut entegrasyonları bozabilir. Profesyonel bir yaklaşım olarak, uç noktalarınızı sürüm numaralarıyla yönetmek en sağlıklı yöntemdir.

• v1: İlk kararlı sürüm.
• v2: Büyük değişiklikler içeren yeni sürüm.

Sürümleme yaparken register_rest_route fonksiyonundaki namespace parametresini kullanın:

// Sürüm 1 için kayıt
register_rest_route('my-plugin/v1', '/data', array(
    'methods' => 'GET',
    'callback' => 'my_v1_handler',
));

// Sürüm 2 için kayıt
register_rest_route('my-plugin/v2', '/data', array(
    'methods' => 'GET',
    'callback' => 'my_v2_handler',
));

Önemli Not: API'nizi yayına almadan önce (deployment), mutlaka WP_DEBUG modunu kapatın ve hata loglarının halka açık bir şekilde görüntülenmediğinden emin olun. Üretim ortamında error_log dosyasını takip ederek API hatalarını izlemek, canlı sistemlerdeki sorunları tespit etmenin en güvenli yoludur.

Sonuç

WordPress ile özel REST API uç noktası oluşturmak, sitenizin işlevselliğini genişletmek ve modern web teknolojileriyle entegre etmek için en etkili yoldur. Bu rehberde öğrendiğiniz register_rest_route kullanımı, yetkilendirme ve veri doğrulama teknikleri, profesyonel bir API geliştirme sürecinin temel taşlarıdır. Bir sonraki adım olarak, oluşturduğunuz bu uç noktaları bir React veya Vue.js uygulaması ile tüketerek dinamik bir arayüz tasarlamayı deneyebilirsiniz.