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

Gereksinimler ve Ön Hazırlık

Özel bir API uç noktası geliştirmeye başlamadan önce, çalışma ortamınızın güncel standartlara uygun olduğundan emin olmalısınız. WordPress REST API, temel olarak WordPress 4.7 sürümü ile çekirdeğe dahil edilmiştir ve 2026 yılı itibarıyla en güncel PHP sürümlerini (8.2 ve üzeri) desteklemektedir.

• PHP Sürümü: En az 8.2 veya üzeri önerilir.
• WordPress Sürümü: 6.0 ve üzeri (güncel güvenlik yamaları için).
• Araçlar: API testleri için Postman veya Insomnia gibi araçlar.
• Kod Editörü: VS Code veya benzeri, PHP eklentileri kurulu bir editör.
• Bilgi Seviyesi: WordPress hook (kanca) yapısı, özellikle register_rest_route fonksiyonu hakkında temel bilgi.

REST API Uç Noktası Kayıt Etme

WordPress'te özel bir API rotası oluşturmak için rest_api_init kancasını kullanırız. Bu kanca, API rotalarının kaydedilmesi için ayrılmış özel bir tetikleyicidir. İlk adım olarak, basit bir "Merhaba Dünya" uç noktası oluşturalım.

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

function ozel_api_test_fonksiyonu( $data ) {
    return new WP_REST_Response( array( 'mesaj' => 'API başarıyla çalışıyor!' ), 200 );
}

Yukarıdaki kod, /wp-json/ozel-api/v1/test adresine yapılan GET isteklerini dinler. register_rest_route fonksiyonu, namespace (isim alanı), route (yol) ve endpoint (uç nokta) ayarlarını tanımlar. WP_REST_Response sınıfı, API yanıtlarını standart JSON formatında döndürmek için kullanılır.

Veritabanından Veri Çekme ve Filtreleme

Gerçek bir senaryoda, API üzerinden genellikle veritabanındaki özel post türlerini veya kullanıcı verilerini çekmek istersiniz. Aşağıdaki örnekte, belirli bir kategorideki son 5 yazıyı çeken bir uç nokta hazırlıyoruz.

add_action( 'rest_api_init', function () {
    register_rest_route( 'ozel-api/v1', '/son-yazilar/(?P\d+)', array(
        'methods'  => 'GET',
        'callback' => 'get_son_yazilar',
        'args'     => array(
            'id' => array(
                'validate_callback' => function($param, $request, $key) {
                    return is_numeric($param);
                }
            ),
        ),
    ));
});

function get_son_yazilar( $data ) {
    $args = array(
        'posts_per_page' => 5,
        'category'       => $data['id']
    );
    $yazilar = get_posts( $args );
    return rest_ensure_response( $yazilar );
}

Burada (?P\d+) ifadesi, URL'den dinamik bir sayısal ID almamızı sağlar. args parametresi, gelen verinin doğrulanması (validation) için kritik bir güvenlik katmanıdır. rest_ensure_response fonksiyonu ise dönen verinin API formatına uygun olduğundan emin olur.

Veri Gönderme ve Güvenlik Önlemleri

API üzerinden veri almak kadar, veri göndermek (POST, PUT, DELETE) de önemlidir. Ancak, dışarıdan gelen her isteğe güvenemeyiz. permission_callback kullanarak sadece yetkili kullanıcıların işlem yapmasını sağlamalıyız.

register_rest_route( 'ozel-api/v1', '/yazi-guncelle', array(
    'methods'  => 'POST',
    'callback' => 'yazi_guncelleme_fonksiyonu',
    'permission_callback' => function () {
        return current_user_can( 'edit_posts' );
    }
));

permission_callback, isteğin işlenmeden önce yetki kontrolünden geçmesini sağlar. Eğer kullanıcı gerekli yetkiye sahip değilse, WordPress otomatik olarak 403 (Forbidden) hatası dönecektir. Bu, API güvenliğinin en temel taşıdır.

Kritik Güvenlik Uyarısı: REST API üzerinden veri gönderirken asla kullanıcıdan gelen veriyi doğrudan veritabanına kaydetmeyin. sanitize_text_field(), absint() veya esc_sql() gibi WordPress temizleme (sanitization) fonksiyonlarını mutlaka kullanın. XSS ve SQL Injection saldırılarına karşı her zaman tetikte olun.

API Yöntemleri Karşılaştırma Tablosu

Hata Yönetimi ve Debug İpuçları

Geliştirme aşamasında hataları yönetmek için WP_Error sınıfını kullanmalısınız. Bu, istemciye sadece "hata" demek yerine, hatanın nedenini (örneğin: "Kullanıcı bulunamadı") anlamlı bir HTTP koduyla iletmenizi sağlar.

function ornek_hata_yonetimi( $request ) {
    $id = $request['id'];
    if ( !post_exists( $id ) ) {
        return new WP_Error( 'post_bulunamadi', 'Bu ID ile bir yazı yok', array( 'status' => 404 ) );
    }
    return get_post( $id );
}

Debug yaparken WP_DEBUG modunu aktif edin. Ayrıca, tarayıcı ağ sekmesinden dönen JSON yanıtlarını incelemek, API geliştirme sürecinde en hızlı geri bildirimi almanızı sağlar.

Sıkça Sorulan Sorular

REST API uç noktalarımı nereden test edebilirim?

Postman veya Insomnia gibi araçlar, HTTP isteklerini (GET, POST, vb.) simüle etmek ve gelen JSON yanıtlarını incelemek için en iyi tercihtir.

Neden permission_callback kullanmalıyım?

Bu fonksiyon, API'nizin yetkisiz kişiler tarafından manipüle edilmesini engeller. Sadece giriş yapmış veya belirli bir yetkiye sahip kullanıcıların işlem yapmasına izin vererek sisteminizi korur.

Verilerimi nasıl önbelleğe (cache) alabilirim?

WordPress'in Transient API yapısını kullanarak veya sunucu tarafında Redis/Memcached gibi çözümlerle API yanıtlarını geçici olarak kaydederek performans artışı sağlayabilirsiniz.

REST API ile özel post türlerini (CPT) çekebilir miyim?

Evet, register_post_type fonksiyonunu kullanırken 'show_in_rest' => true parametresini eklemeniz yeterlidir. WordPress bunu otomatik olarak API'ye dahil eder.

API yanıtlarını nasıl özelleştirebilirim?

register_rest_field fonksiyonunu kullanarak mevcut uç noktalara yeni alanlar ekleyebilir veya tamamen özel bir uç nokta oluşturarak yanıt yapısını istediğiniz gibi kurgulayabilirsiniz.

Yasal Sorumluluk Reddi: Bu makalede paylaşılan kod örnekleri eğitim amaçlıdır. Üretim (production) ortamında kullanmadan önce güvenlik denetimlerini yapmalı ve veritabanı işlemlerinde mutlaka hazırlıklı ifadeler (prepared statements) kullanmalısınız. Oluşabilecek veri kayıplarından yazar sorumlu tutulamaz.

API Performansını Optimize Etme ve Veritabanı Yükünü Azaltma

Özel uç noktalarınız üzerinden yoğun trafik alıyorsanız, WordPress veritabanına yapılan her sorgu sitenizin genel performansını olumsuz etkileyebilir. API yanıtlarını optimize etmek, hem sunucu kaynaklarını korur hem de istemci tarafında daha hızlı bir deneyim sunar. İşte performans artışı için uygulayabileceğiniz temel stratejiler:

Transient API ile Yanıtları Önbelleğe Alma

Veritabanından karmaşık sorgularla veri çekiyorsanız, bu veriyi belirli bir süre için set_transient() fonksiyonu ile önbelleğe almalısınız. Bu sayede her istekte veritabanına gitmek yerine, hazır yanıtı döndürebilirsiniz.

add_action('rest_api_init', function () {
    register_rest_route('custom/v1', '/data', array(
        'methods' => 'GET',
        'callback' => 'get_cached_custom_data',
    ));
});

function get_cached_custom_data() {
    $cache_key = 'custom_api_data_cache';
    $data = get_transient($cache_key);

    if (false === $data) {
        // Veritabanı sorgusu burada yapılır
        $data = array('status' => 'success', 'items' => 'Veritabanı verisi');
        set_transient($cache_key, $data, HOUR_IN_SECONDS);
    }

    return new WP_REST_Response($data, 200);
}

API Yanıtlarında Alan Filtreleme

İstemciye sadece ihtiyaç duyulan veriyi göndermek, JSON yanıt boyutunu küçültür. _fields parametresini destekleyen bir yapı kurarak, istemcinin sadece istediği alanları almasını sağlayabilirsiniz.

Gelişmiş Hata Ayıklama ve Loglama Süreçleri

Üretim ortamında API hatalarını izlemek, sistemin sürdürülebilirliği için kritiktir. WordPress'in yerleşik WP_DEBUG_LOG özelliğini kullanarak API hatalarını bir dosyaya kaydedebilir veya özel bir hata takip sistemi kurabilirsiniz.

Özel Hata Kodları ve Loglama

Hataları standart bir JSON formatında döndürmek, istemci tarafındaki geliştiricilerin hata ayıklamasını kolaylaştırır. Aşağıdaki örnek, bir hata oluştuğunda hem log kaydı tutar hem de anlamlı bir hata mesajı döner:

function log_and_return_error($message, $code = 500) {
    error_log('API Hatası: ' . $message);
    return new WP_Error('api_error', $message, array('status' => $code));
}

// Kullanımı:
if (empty($request['id'])) {
    return log_and_return_error('ID parametresi eksik.', 400);
}

Bu yöntemle, API uç noktalarınızdaki aksaklıkları wp-content/debug.log dosyasından takip edebilir, kullanıcıya ise sistemin neden başarısız olduğunu açıklayan net bir hata kodu iletebilirsiniz.

Sonuç

WordPress ile özel REST API uç noktaları oluşturmak, sitenizi statik bir içerik platformundan dinamik bir veri kaynağına dönüştürür. Bu eğitimde, temel rota tanımlamadan veri güvenliğine, hata yönetiminden yetkilendirme süreçlerine kadar profesyonel bir API geliştirme döngüsünü ele aldık. Bir sonraki adım olarak, JWT (JSON Web Token) kullanarak API kimlik doğrulamasını daha güvenli hale getirmeyi ve API yanıtlarınıza özel meta veriler eklemeyi araştırmanızı öneririm.