Kaçırmayın—API ihtiyaçları için **Apidog**'a güvenen binlerce geliştiriciye katılın. Şimdi indirin ve API geliştirme, test etme ve belgelemede çok daha uygun fiyata farkı deneyimleyin!
Bir projede üçüncü taraf bir API çağırmanız gerekmiş olabilir veya farklı sistemlerin birbiriyle nasıl iletişim kurduğunu öğreniyor olabilirsiniz. Dokümantasyona göre bir istek gönderdiğinizde, genellikle açıklanamayan hata yanıtları alırsınız: 400 Hatalı İstek, 401 Yetkisiz veya basitçe hiçbir şey dönmez.
Sorunlar genellikle basit görünen ancak aslında çok önemli ayrıntılarda yatar: yanlış istek formatı, eksik gerekli Başlık bilgisi, yanlış kimlik doğrulama yöntemi veya API'nin beklediğiyle veri formatı uyuşmazlığı. Bu temel kavramlar net bir şekilde anlaşılmazsa, her API çağrısı kumar gibi hissettirir.
İsteklerin ve yanıtların her bir bileşenini gerçekten anlamanız ve kendi rollerini bilmeniz gerekir, böylece sorunlar ortaya çıktığında nedeni hızla belirleyebilirsiniz.
Ardından, en temel kavramlardan başlayarak API etkileşimlerinin tüm sürecini adım adım açıklayacağız.
İstekler: Sunucuya Ne Söylersiniz?
Sunucudan bilgi almak veya sunucunun bir işlem yapmasını sağlamak istediğinizde, bir istek göndermeniz gerekir.
Eksiksiz bir API isteği birkaç temel öğe içerir. İlki istek yöntemidir; en yaygın olanları GET, POST, PUT, DELETE'tir.
- GET, veri almak için kullanılır;
- POST, yeni veri oluşturmak için kullanılır;
- PUT, mevcut verileri güncellemek için kullanılır;
- DELETE, verileri silmek için kullanılır.
Yönteme ek olarak, isteğin bir URL belirtmesi gerekir; bu, sisteme erişmek istediğiniz belirli kaynağın nerede bulunduğunu söyler. Örneğin, https://api.weather.com/current/beijing açıkça Pekin'in mevcut hava durumu bilgisini almak istediğinizi gösterir.
Ancak sadece yöntem ve URL yeterli değildir; çoğu zaman sunucuya daha fazla bilgi aktarmanız gerekir. İşte burada isteğin diğer kısımları devreye girer: Başlık (Header) ve Gövde (Body).
Başlık (Header): İstek İçin Ek Talimatlar
Başlık, istekle ilgili çeşitli meta verileri içerir ve sunucunun isteğinizi daha iyi anlamasına ve işlemesine yardımcı olur.
En temel Başlık, gönderdiğiniz verinin hangi formatta olduğunu sunucuya bildiren Content-Type'tır. JSON verisi gönderiyorsanız, Content-Type: application/json olarak ayarlayın. Form verisi gönderiyorsanız, Content-Type: application/x-www-form-urlencoded olarak ayarlayın.
Bir diğer önemli Başlık, isteği hangi istemcinin gönderdiğini belirten User-Agent'tır. Tarayıcılar bu değeri otomatik olarak ayarlar ve isteğin Chrome, Firefox veya başka bir tarayıcıdan gelip gelmediğini sunucuya bildirir.
Accept Başlığı, yanıt için hangi formatı beklediğinizi sunucuya bildirir. Örneğin, Accept: application/json, sunucunun veriyi JSON formatında döndürmesini istediğiniz anlamına gelir.
Ayrıca Cache-Control gibi önbellek kontrolü için Başlıklar da vardır; bunlar sunucuya veya ara proxy sunucularına önbelleklemeyi nasıl ele alacakları konusunda talimat verebilir. Bu Başlıklar teknik görünebilir, ancak onları anlamak API davranışını daha iyi kontrol etmenize yardımcı olur.
Gövde (Body): İsteğin Belirli İçeriği
Sunucuya büyük miktarda veri göndermeniz gerektiğinde, bu veri Gövde'ye gider.
GET istekleri genellikle Gövde içermez, çünkü GET esas olarak veri almak içindir ve gerekli parametreler doğrudan URL'ye yerleştirilebilir. Ancak POST ve PUT gibi istekler, veri taşımak için genellikle bir Gövde'ye ihtiyaç duyar.
En yaygın Gövde formatı JSON'dır. Örneğin, bir web sitesine kullanıcı kaydederken, tarayıcınız aşağıdaki gibi görünebilecek bir Gövde ile bir POST isteği gönderir:
{
"username": "john_doe",
"email": "john@example.com",
"password": "secretpassword"
}
Bir diğer yaygın Gövde formatı, özellikle dosya yüklerken kullanılan form-data'dır. Bu format hem metin verisi hem de dosya verisi içerebilir, bu da onu karmaşık form gönderimlerini işlemek için ideal kılar.
Bazı API'ler Gövde için XML formatını kullanır, ancak günümüzde JSON'dan daha az yaygın olsa da, belirli kurumsal sistemlerde hala yaygın olarak kullanılmaktadır. Formattan bağımsız olarak, anahtar nokta Content-Type Başlığının Gövdenin gerçek formatıyla eşleştiğinden emin olmaktır.
Yanıtlar: Sunucunun Size Cevabı
Sunucu isteğinizi aldığında, bir yanıt döndürür. Yanıt yapısı isteğe benzer, Başlık ve Gövde içerir, ancak ek önemli bir öğe ile: durum kodu.
Durum kodu, isteğin işleme sonucunu size bildiren üç haneli bir sayıdır. 200 başarıyı gösterir, bu da en çok görmeyi umduğunuz şeydir. 404, istenen kaynağın bulunamadığı anlamına gelir, yani meşhur "404 hatası". 500, dahili bir sunucu hatasını gösterir, bu genellikle sunucu tarafında bir şeylerin ters gittiği anlamına gelir.
Yanıt Başlığı, yanıtla ilgili çeşitli bilgiler içerir. Content-Type size yanıt verisinin formatını söyler, Content-Length size yanıt verisinin boyutunu söyler ve Set-Cookie istemcide çerezleri ayarlamak için kullanılır.
Yanıt Gövdesi, istediğiniz gerçek veriyi içerir. Hava durumu bilgisi istiyorsanız, Gövde sıcaklık, nem, rüzgar hızı vb. içerebilir. Kullanıcı bilgisi istiyorsanız, Gövde kullanıcı adı, e-posta, kayıt zamanı vb. içerebilir.
Yanıt yapısını anlamak, API çağrısının başarılı olup olmadığını ve döndürülen veriyi nasıl işleyeceğinizi belirlemenize yardımcı olur. API çağrıları yanlış gittiğinde, durum kodunu ve yanıt Gövdesini kontrol etmek genellikle sorunları teşhis etmenin ilk adımıdır.
Kimlik Doğrulama (Auth): Kimliğinizi Kanıtlama
En değerli API'ler bir tür kimlik doğrulama gerektirir. Tıpkı belirli yerlere girmek için bir kimliğe ihtiyacınız olduğu gibi, korumalı API'lere erişmek için kimlik bilgileri sağlamanız gerekir.
En basit kimlik doğrulama yöntemi API Anahtarıdır. Servis sağlayıcı size benzersiz bir anahtar verir ve siz bunu her isteğe dahil edersiniz. API Anahtarları genellikle Başlıkta, örneğin Authorization: Bearer your-api-key-here şeklinde yer alır.
Bir diğer yaygın yöntem Temel Kimlik Doğrulama'dır (Basic Authentication). Bir kullanıcı adı ve parola sağlarsınız ve istemci bunları kodlayarak Authorization Başlığına yerleştirir. Basit olmasına rağmen, bu yöntemin güvenliği nispeten düşüktür.
OAuth, daha karmaşık ancak güvenli bir kimlik doğrulama yöntemidir. Kullanıcıların, doğrudan parola sağlamadan üçüncü taraf uygulamalara verilerine erişim yetkisi vermesini sağlar. WeChat kullanarak diğer uygulamalara giriş yaptığınızda, OAuth sürecini kullanıyorsunuz demektir.
JWT (JSON Web Token) bir başka popüler kimlik doğrulama yöntemidir. Bir kullanıcı giriş yaptıktan sonra, sunucu kullanıcı bilgilerini içeren bir token oluşturur ve kullanıcı bunu sonraki isteklerde taşır. JWT'nin faydası, sunucunun oturum bilgilerini saklamasına gerek kalmaması, bu da sistem ölçeklenebilirliğini artırmasıdır.
Bir kimlik doğrulama yöntemi seçimi, özel ihtiyaçlarınıza ve güvenlik gereksinimlerinize bağlıdır. Basit kişisel projeler için API Anahtarı yeterli olabilir. Kullanıcı girişi gerektiren uygulamalar için OAuth veya JWT daha uygun olabilir.
Pratik Uygulama: Bu Kavramları Bir Araya Getirme
Şimdi bu kavramların belirli bir örnek üzerinden nasıl birlikte çalıştığına bakalım. Bir blog uygulaması geliştirdiğinizi ve yeni bir makale oluşturmanız gerektiğini varsayalım.
İlk olarak, https://api.myblog.com/articles adresine bir POST isteği gönderirsiniz. İstek Başlığı, veri formatını belirtmek için Content-Type ve kimlik doğrulama bilgisi sağlamak için Authorization içerir:
POST /articles HTTP/1.1
Host: api.myblog.com
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Gövde, makalenin belirli içeriğini içerir:
{
"title": "API Temellerine Giriş",
"content": "Bu, API'lere ayrıntılı bir giriştir...",
"tags": ["API", "Programlama", "Başlangıç"]
}
İsteği aldıktan sonra, sunucu önce makale oluşturma izniniz olup olmadığını doğrulamak için Authorization Başlığındaki token'ı doğrular. Ardından Gövdedeki JSON verisini ayrıştırır ve yeni bir makale kaydı oluşturur.
Her şey sorunsuz giderse, sunucu 201 durum kodu (başarılı oluşturulduğunu gösterir) döndürür. Yanıt Başlığı, yeni oluşturulan makalenin konumunu içerebilir ve Gövde, sistem tarafından oluşturulan kimlik ve oluşturulma zamanı dahil olmak üzere tam makale bilgilerini içerir:
{
"id": 12345,
"title": "API Temellerine Giriş",
"content": "Bu, API'lere ayrıntılı bir giriştir...",
"tags": ["API", "Programlama", "Başlangıç"],
"created_at": "2024-01-15T10:30:00Z",
"author_id": 678
}
Bu eksiksiz süreç, isteklerin, yanıtların, Gövde'nin, Başlık'ın ve Kimlik Doğrulama'nın nasıl birlikte çalıştığını gösterir. Her parçanın kendi rolü vardır, ancak hepsi birlikte tam bir API etkileşimini tamamlar.
Hata Ayıklama ve Test Etme: API Geliştirmeyi Daha Sorunsuz Hale Getirme
API'leri gerçekten kullanmaya başladığınızda, kaçınılmaz olarak çeşitli sorunlarla karşılaşacaksınız. İstek gönderilir, ancak bir hata durum kodu döndürür; veya yanıt veri formatı beklediğiniz gibi değildir; veya kimlik doğrulama her zaman başarısız olur.
Bu noktada, eksiksiz istek ve yanıt içeriğini görüntüleyebilmeniz gerekir. Tarayıcının geliştirici araçları iyi bir başlangıç noktasıdır, çünkü Başlık ve Gövde dahil tüm HTTP isteklerini görüntüleyebilirler. Daha karmaşık API testleri için Apidog kullanmak daha faydalı olacaktır.
Yaygın sorunlar arasında Content-Type uyuşmazlıkları, kimlik doğrulama bilgisi hataları, yanlış istek formatları vb. bulunur. Durum kodunu ve hata mesajlarını dikkatlice kontrol etmek genellikle sorunu hızlı bir şekilde bulmanıza yardımcı olur.