Nedir Bu API Key?
REST API, geliştiricilerin HTTP protokolünü kullanarak GET ve POST gibi isteklerde bulunup, bu isteklere çeşitli formatlarda yanıt aldığı bir dağıtık sistemdir. REST (REpresentational State Transfer), Temsili Durum Aktarımı olarak Türkçede de kullanılır. REST’in tüm prensiplerini yerine getiren API’ler ise RESTful olarak nitelendirilir. REST API ilk defa 2000 yılında Roy Fielding tarafından doktora tezinin bir bölümü olarak geliştirilmiş ve ardından geliştiricilerce kabul görmüştür. REST API, web mimarisi kısmında çalışsın veya çalışmasın her geliştiricinin birgün ihtiyaç duyabileceği popüler bir API’dir.
REST API, gelişticilerin hakim olduğu SOAP ve WSDL tabanlı web servislerine benzer ancak daha basite indirgenerek geliştirilmiştir. REST API kullanılırken web tarayıcılarının sayfa transfer sürecini bir parçası olan HTTP fiilleri kullanılarak haberleşilir. Dolayısıyla geliştirici olarak size tanıdık gelen GET, POST, PUT DELETE vb. filler REST API ile haberleşmede oldukça yaygın kullanılır. HTTP protokolünü kullanıyor olması nedeniyle REST API’i pratik olarak herhangi bir programlama dilinde kullanabilir. REST API’yi yazılımlarınızda kullanarak yazılımınızın uzun ömürlü olmasını sağlayabilir ve gelişimini pozitif yönde destekleyebilirsiniz.
REST ile aktarılan verilerin formatı HTML, JSON, XML veya farklı bir formata sahip olabilir. Diğer katı kurallı ve dediğim dedik API’lerin aksine REST, geliştiriciler için bu konuya bir kısıtlama getirmiyor.
Twitter’ın oldukça popüler bir REST API’si mevcut. Bu API yardımıyla son tweet’leri çekebilir, ya da ekleyeceğiniz çeşitli parametrelerle arama dizgisi veya hashtag’in sonucunu JSON formatında sonuç olarak alabilirsiniz. Örneği HTTP isteği göndererek Twitter API üzerinden “xentr” sözcüğüyle eşleşen en güncel tweet’leri çekmek için şu kod satırını kullanabilirsiniz;
Geliştiriciler için REST API yeteneklerini kendisi belirler. Bu yeteneklerin nasıl ve ne şekilde kullanılacağını, parametreleri, yanıt formatını, istek sorgusu sınırını, genel kullanım durumunu, API anahtarlarını, metotları (GET, POST, PUT ve DELETE gibi), dil desteğini, Callback kullanımını, HTTPS desteğini ve diğer kullanımları açıklaması gerekir. API’ye ilişkin olarak şirketin yayınladığı dokümantasyonu incelemeniz halinde, API’yi kullanmanız için birinci dereceden önem arz eden bu özellikleri kavrayabilirsiniz.
Bildiğiniz gibi XenForo 2.1'de bir REST API eklendi. Bu, programlı olarak bir XenForo kurulumunun birçok alanı ile etkileşime girmenizi sağlar.
<XenForo base URL>/api/ URL formatı ile API alanına erişim yapabilirsiniz.
API'ye erişmek, yönetici kontrol paneli üzerinden bir anahtar oluşturmayı gerektirir. API'ye kimliği doğrulanmamış bir erişim yoktur ve kullanıcılar şu anda API'ye erişmek için kendi anahtarlarını oluşturamazlar.
Xenforo üzerinde API varsayılan olarak etkindir. Gerekirse, tüm API erişimini
src / config.php dosyasına aşağıdakileri ekleyerek hızla devre dışı bırakılabilirsiniz.API anahtarları
API anahtarları, Yönetici> kontrol panelinden Ayarlar> API anahtarları'na giderek oluşturulur .
API anahtarları oluşturmak yüksek derecede ayrıcalıklı verilere erişime izin verebileceğinden, yalnızca süper yöneticiler bu sisteme erişebilir. İsteğin geçerli olmasını sağlamak için bir API anahtarı oluşturulduğunda tüm süper yöneticiler bir e-posta bilgilendirmesi alır.
Bir anahtar oluşturulduğunda, rastgele bir dize oluşturulur ve bu, API ile kendinizi doğrulamak için kullanılır. Bu anahtarın gizli tutulması önemlidir. Bir API anahtarının ele geçirildiğini düşünüyorsanız, anahtarı hemen yeniden oluşturmanız ve eski api anahtarını kullanıldığı alanları güncellemeniz gerekir.
Anahtar türleri
Tüm API erişimi, belirli bir kullanıcı bağlamında yapılır. Örneğin, API’ye "Ovunc Dinc" olarak erişiyorsam ve bir konu gönderen bir istek yaparsam, bu konu "Ovunc Dinc" tarafından oluşturulmuş olur. Çoğu durumda, API bu kullanıcı için belirtilen izinlere de saygı gösterir, böylece foruma göz atarken normalde görmeyecekleri verilere erişemezler.
Bunun üzerinde kontrole izin vermek için üç tip API anahtarı vardır:
- Ziyaretçi/misafir anahtarı - bu anahtar API'ye her zaman konuk kullanıcı olarak erişir. Bu istekler her zaman konuk izinlerine saygılı olacaktır. Örneğin, konuklar konulara cevap veremiyorsa, bir konuya cevap vermek için bir API isteği izin hatası oluşturmaz.
- Kullanıcı anahtarı - bu anahtar API’ya her zaman belirtilen bir kullanıcı olarak erişir ve her zaman bir konuk anahtarına benzer şekilde bu kullanıcının izinlerine saygı gösterir.
- Süper kullanıcı anahtarı - bu anahtar, ek bir değer ileterek API'ye herhangi bir kullanıcı olarak erişebilir. İsteğe bağlı olarak, bu anahtar istekte bulunan kullanıcının izinlerini atlayarak eylemde bulunmalarına veya normalde erişemeyecekleri içerikleri görüntülemelerine izin verebilir.
Anahtar kapsamlar
Uzatılmış bir anahtarın verebileceği hasar miktarını sınırlandırmak için, her anahtar erişebileceği API kapsamlarını kontrol edebilir. Kapsamlar, istekte bulunan kullanıcının izinlerinden bağımsız olarak API alanlarına erişimi sınırlar.
API'deki her son nokta daha fazla kapsamdan biri tarafından ele alınacaktır. API bu kapsamlardan herhangi birine verilmemişse, istek başarısız olur.
Güvenlik için, yalnızca gereksinim duyduğunuz kapsamların anahtarını vermenizi öneririz. Daha sonra ek kapsamlar istiyorsanız, gerektiğinde eklenebilirler.
API’ye erişme
API'ye erişmek ve bir anahtarınız olması için URL’yi öğrendikten sonra, talepte bulunmaya başlayabilirsiniz.
İkili bir dosyanın özel olarak istendiği durumlar dışında (bir ek indirirken olduğu gibi), tüm API yanıtları JSON formatında döndürülür. Hatalar her zaman 400 aralığında bir yanıt kodu döndürür. Başarılı istekler 200 kodunu döndürür. Yaygın olarak kullanılmamasına rağmen, yönlendirmeler 300 kodlu bir kod döndürür.
İstek gövdeleri, application/x-www-form-urlencodedkodlama veya bir dosya yükleniyorsa, multipart/form-datakodlama kullanılarak gönderilmelidir. Parametreler ayrıca sorgu dizesi aracılığıyla iletilebilir.
Tüm istek verileri UTF-8 karakter kümesini kullanmalıdır.
İstekler,
XF-Api-Key başlık üzerinden kullanmak için API anahtarını geçmelidir . Bu tüm isteklerde bulunmalıdır.Seçilen API anahtarı bir süper kullanıcı anahtarıysa, içerik kullanıcısının kullanıcı kimliğini
XF-Api-User başlık aracılığıyla iletebilirsiniz . Hiçbir kullanıcı kimliği geçilmezse, içerik varsayılan olarak bir misafir olarak belirlenir.İstek bir süper kullanıcı anahtarıyla yapılırsa ve içerik kullanıcısının izinlerini atlamak istiyorsanız,
api_bypass_permissionsparametre 1 olarak ayarlanarak istek başına gerçekleştirilebilir.Hata işleme
Bir hatayla karşılaşıldığında, yanıt kodu 400 aralığında olacaktır. Arada sırada, sunucunun isteği işleyemediğini göstermesine rağmen 500 aralıklı bir hata oluşabilir. API geçici olarak devre dışı bırakılabilir veya başka bir sunucu hatası meydana geldi.
Hata mesajları standart bir formata sahiptir. İşte bir örnek:
Üst seviye, errorsanahtarı olan bir nesne olacaktır . Bu, 1 veya daha fazla giriş içeren bir dizi olacaktır. Her giriş aşağıdaki parametrelere sahip bir nesnedir:
code- Bu, hata için makineyle okunabilen bir koddur. Duruma bağlı oldukları için birçok olası hata kodu vardır.message- hatanın okunabilir bir versiyonu. Bu değişebilir veya çevrilebilir ve hatanın türünü belirlemek için kullanılmamalıdır.params- bu, tetiklenen hatayla alakalı anahtar-değer parametrelerinin bir listesidir. Hatayla ilgili daha ayrıntılı bilgi vermek için hata kodunu ve mesajı ekleyebilirler.
API, alınabilecek birkaç uç nokta ve eylem içeriyor.
XenForo'da API bitiş noktası belgelerini görüntüleyin.
Bu son nokta dokümantasyonu API verilerinden ve koddaki yorumlardan üretilmiştir. Zamanla genişletilecek ve güncellenecektir.
- Bilgi Kaynak Erişimi
- https://xentr.net/
Son düzenleme:
