API adresi (endpoint) nedir?

API adresi (endpoint) nedir?​

API adresi veya endpoint, web API bağlamında uygulamanın belirli bir veriye ya da işleme erişmek için istek kabul ettiği uç noktadır. URL ile HTTP metodu birlikte işlemi ayırt eder; aynı adreste GET ve POST farklı işlemler olabilir. Web dışındaki API türlerinin tümü HTTP kullanmak zorunda değildir. İstemci uygulama bu adrese genellikle HTTP yöntemiyle (GET, POST, PUT, PATCH veya DELETE) istek gönderir; sunucu da veri, işlem sonucu ve HTTP durum koduyla yanıt verir. Kısaca endpoint, istemci ile sunucudaki belirli işlev arasındaki giriş noktasıdır.

Endpoint nasıl çalışır?​

Bir API yalnızca alan adından oluşmaz. İsteğin anlamını; HTTP yöntemi, adres yolu, başlıklar, kimlik doğrulama bilgisi, sorgu parametreleri ve istek gövdesi birlikte belirler. Örneğin GET /api/products/42 belirli bir ürünü okumayı, POST /api/products ise yeni ürün oluşturmayı ifade edebilir.

Sunucu isteği işledikten sonra çoğunlukla JSON biçiminde yanıt verir. 200 başarılı bir okumayı, 201 yeni kaydın oluşturulduğunu, 400 hatalı istek gönderildiğini, 401 geçerli kimlik doğrulama bilgisinin bulunmadığını, 404 kaynağın bulunamadığını, 500 ise sunucu tarafında beklenmeyen bir hata oluştuğunu anlatır. Kesin anlam, ilgili API'nin dokümantasyonunda tanımlanır.

Somut örnek: ürün endpoint'i​

Bir mağaza uygulamasının ürünleri sunduğunu varsayalım. Ürün listesini okumak için endpoint şu olabilir:


Bu istekte GET okuma işlemini, /api/products kaynak yolunu, category=keyboard ise filtreleme parametresini belirtir. Başarılı bir yanıtın gövdesi örneğin şöyle olabilir:


İstemci bu yanıtı alıp ürün listesini ekranda gösterebilir. Liste boşsa endpoint çalışmıyor anlamına gelmez; filtreye uyan ürün bulunmamış olabilir. 404 yanıtı alırsanız yolun ve kaynak kimliğinin doğru olduğunu, 401 alırsanız kimlik doğrulama bilgisinin gönderildiğini kontrol edin.


Bu adresler ve ürünler kurgu örnektir; example.com üzerinde çalışan bir ürün API'si iddia edilmiyor. Kendi API'nizde başlangıç kontrolü şöyle yapılabilir:

1. API dokümantasyonundaki HTTP yöntemini ve yolu belirleyin; örnekte GET /api/products kullanılır.
2. Gerekliyse sorgu parametrelerini ve kimlik doğrulama başlıklarını ekleyin.
3. İsteği API istemcisi veya komut satırından gönderin: curl -i "https://example.com/api/products"
4. HTTP durum kodunu ve yanıt gövdesini birlikte değerlendirin. Başarılı yanıtta beklenen JSON alanlarını görüyorsanız sonraki adım, bu alanları uygulamanızdaki veri modeline eşlemektir.
5. Hata alırsanız yöntemi, endpoint yolunu, parametre adlarını, içerik türünü ve yetkilendirmeyi sırayla karşılaştırın.

Bu örnekte beklenen başarı işareti, API'nin tanımladığı başarılı HTTP kodu ile geçerli JSON yanıtıdır. Yalnızca tarayıcıda bir adres açılması yeterli kanıt değildir; tarayıcı çoğunlukla GET gönderir ve POST gibi yöntemleri, başlıkları veya gövdeyi tek başına doğru şekilde oluşturmaz.

Endpoint tasarımında temel kararlar​

Aynı kaynağın farklı işlemleri için yöntemi değiştirmek, gereksiz ve belirsiz yol adlarını azaltır. Aşağıdaki yaklaşım yaygındır:

Bu tablo katı bir zorunluluk değil, anlaşılır bir başlangıç düzenidir. API'nin mevcut sözleşmesi farklıysa istemci, kendi varsayımını değil dokümantasyonda belirtilen yöntemi ve yanıt biçimini kullanmalıdır. Endpoint değiştirildiğinde eski istemcilerin bozulmaması için sürümleme, geriye dönük uyumluluk veya açık bir geçiş planı da düşünülmelidir.

Sık yapılan anlamlı hatalar​

Yalnız yolu kontrol etmek: /api/products/42 yolu doğru olsa bile yanlış HTTP yöntemi, eksik başlık veya hatalı gövde isteği başarısız yapabilir.

Kimlik ile sorgu parametresini karıştırmak: /api/products/42 belirli bir ürünü, /api/products?category=keyboard ise koleksiyon üzerinde filtrelemeyi temsil eder. Bu ikisinin sunucu tarafındaki anlamı aynı değildir.

Durum kodunu yok saymak: JSON gövdesi dönmüş olması işlemin başarılı olduğu anlamına gelmez. Uygulama önce HTTP durum kodunu, sonra yanıt biçimini ve hata alanlarını değerlendirmelidir.

Yanıt biçimini varsaymak: Bazı endpoint'ler doğrudan dizi, bazıları items alanı içeren nesne döndürür. İstemci kodunu gerçek API sözleşmesine göre yazın; değişebilen alanları doğrulamadan kullanmayın.

Sık sorulan sorular​

Endpoint ile API aynı şey midir?​

Hayır. API, uygulamanın sunduğu genel arayüz ve kurallar bütünüdür; endpoint ise bu API içindeki belirli bir istek adresidir. Tek bir API birden fazla endpoint içerebilir.

Base URL ile endpoint adresi arasındaki fark nedir?​

Base URL, sunucuya ulaşan ortak başlangıç adresidir; örneğin https://api.example.com/v1. Dokümandaki /products/42 yolu bunun sonuna eklenebilir. Sürüm önekini iki kez eklememek ve doğru ortamın adresini kullanmak gerekir; son URL'yi göndermeden önce kontrol edin.