RESTful API'lerin Geliştirilmesinde Kullanılan HTTP Header'lar

HTTP başlıkları, RESTful API'lerin geliştirilmesinde son derece önemlidir Bu başlıklar sayesinde API'lerle HTTP protokolü arasında iletişim kolaylaşır HTTP başlıklarını doğru bir şekilde kullanarak, RESTful API'lerin performansını artırabilir ve daha güvenli hale getirebilirsiniz Bu yazıda, RESTful API'lerin geliştirilmesinde kullanılan HTTP başlıkları hakkında detaylı bilgiye sahip olacaksınız

API'ler, web uygulamalarının ve cihazların birbirleriyle etkileşim kurmasını sağlayan önemli bir araçtır. Bununla birlikte, API'lerin oluşturulmasında, HTTP protokolünün sunduğu özelliklerin doğru kullanımı oldukça önemlidir. RESTful API'lerin geliştirilmesinde sıkça kullanılan HTTP header'ları, bu konuda büyük önem taşımaktadır.

Bu makale, RESTful API'lerin geliştirilmesinde kullanılan HTTP header'larını inceleyerek, bu header'ların ne amaçla kullanıldığını ve nasıl kullanıldığını açıklamaktadır. Bu kapsamda, Authorization, Content-Type, CORS, Cache-Control, User-Agent ve Accept header'ları ele alınmaktadır.

Authorization Header

RESTful API'lerinde, API kullanıcılarının kimlik doğrulaması için kullanılan bir header Authorization Header'dır. Bu header, bir API isteği yapan kullanıcının kimliğini doğrulamak için kullanılır. Kimlik doğrulama işlemi başarısız olursa, API isteği reddedilir ve kullanıcının istediği veriye erişemesi engellenir.

Authorization Header, genellikle bir kullanıcı adı (username) ve şifre (password) kombinasyonu veya bir token (anahtar) içerir. Bu header sayesinde, API hizmetinin yanıtladığı taleplerin hangi kullanıcıların tarafından gönderildiği bilgisi sağlanır. Bu sayede API hizmeti, kimlik doğrulaması sonrasında yalnızca yetkili kullanıcılara veri önerebilir.

Content-Type Header

Content-Type header, bir RESTful API'nin girdi veya çıktı aldığı verinin türünü belirler. Bu header, veriyi JSON, XML, HTML veya herhangi bir diğer formatta alınabileceğini gösterir.

Bir örnek vermek gerekirse, bir Get isteğiyle bir API'ye JSON formatında dataları almak istediğimizde, Content-Type header'ının aşağıdaki gibi olması gerekir:

Header Adı	Değer
Content-Type	application/json

Bu örnekte, Content-Type header'ı application/json olarak ayarlandı, bu da API tarafından JSON formatındaki verilerin beklenmesi gerektiğini gösterir.

Başka bir örnek de, bir POST isteğiyle API'ye bir XML dosyası yüklemek istediğimizde, Content-Type header'ının aşağıdaki gibi olması gerekir:

Header Adı	Değer
Content-Type	application/xml

Bu örnekte, Content-Type header'ı application/xml olarak ayarlandı, bu da API tarafından XML formatındaki verilerin beklenmesi gerektiğini gösterir.

Bu header'ın kullanımı RESTful API'lerde oldukça yaygındır ve hem giriş hem de çıkış için belirli veri türlerini ayarlamayı kolaylaştırır.

JSON Veri Türü

Bir RESTful API, uygulama geliştiricilerinin uygulamalarına veri eklemelerini, güncellemelerini, alma ve silmelerini sağlayan bir yazılım arayüzüdür. API'ler, birden fazla uygulama ve sistem arasında veri alışverişini kolaylaştırmak için kullanılır. RESTful API'ler, HTTP protokolünü kullanarak çalışır ve HTTP header'ları API'nin nasıl çalışacağına dair bilgi sağlar. Bu makalemizde RESTful API'lerin geliştirilmesinde sıkça kullanılan HTTP header'larını inceleyeceğiz.

API'ye gönderilen veya API'den alınan verinin türünü belirleyen en yaygın header'lar Content-Type header'larıdır. Content-Type header, gönderilen veya alınan içeriğin türünü gösteren bir MIME tipi belirtir. RESTful API'lerde, JSON veya XML genellikle kullanılan iki veri türüdür. JSON, son yıllarda API'lerde en yaygın olarak kullanılan format olmuştur.

JSON standart bir veri formatıdır ve aynı zamanda insanlar tarafından da okunabilen bir yapıda olması nedeniyle tercih edilir. Bir JSON mesajı, bir nesne biçiminde yazılmış anahtar-değer çiftleri listesidir. Anahtarlar, çift tırnak içinde olmalıdır, değerler ise tipik olarak sayı, dize, mantıksal, nesne veya dizi olabilir.

API'ye JSON verisi göndermek veya almak istiyorsanız, Content-Type header'ını aşağıdaki örnekte olduğu gibi 'application/json' olarak ayarlamanız gerekiyor:

Header	Değer
Content-Type	application/json

Bir RESTful API geliştiricisi olarak, JSON formatını kullanmanızı öneririz. JSON, daha hızlı, daha az veri taşır ve web ölçekli uygulamalar için mükemmel bir seçimdir.

XML Veri Türü

API'ye gönderilen veya API'den alınan verinin türünü belirten HTTP header'lardan biri de Content-Type header'dır. Bu header, API'ye gönderilen verinin hangi formatta olduğunu belirtir. XML, API'ye gönderilen veya API'den alınan verinin XML formatında olduğunu belirten bir Content-Type header örneğidir.

XML, Extensible Markup Language olarak bilinir ve web uygulamalarında kullanılan bir veri formatıdır. Genellikle makine tarafından okunabilir ancak insanların anlaması zor olan bir veri türüdür. XML, birden fazla uygulama tarafından kullanılabilecek şekilde tasarlanmıştır ve bu nedenle web API'lerinde oldukça sık kullanılır.

XML formatında veri alan bir API'ye örnek verecek olursak, birçok haber sitesi API'si XML formatında veri döndürür. Bu şekilde, diğer uygulamalar kolayca bu veriyi okuyup kullanabilirler. XML formatı ayrıca, bazı arama motorları tarafından web sayfalarındaki verileri toplamak için de kullanılır.

API geliştirirken, API'ye gönderilen veya API'den alınan verinin türünü belirtmek için Content-Type header'ının doğru şekilde kullanılması önemlidir. XML formatında veri kullanacak API'lerde Content-Type header'ına "application/xml" eklenmelidir. Bu sayede, API'ye veri gönderen uygulamaların ve API'den veri alan uygulamaların doğru şekilde çalışması sağlanabilir.

CORS Header

CORS (Cross-Origin Resource Sharing) Header, API'lerin farklı bir etki alanından gelen istekleri kabul etmesi için kullanılan bir HTTP header'dır. Bu header, sık sık özelleştirilir, çünkü bir API, özelleştirilen etki alanlarından (domain) gelen istekleri kabul etmek isteyebilir. CORS Header, API'nin girişlerini korumak ve izinsiz erişimleri önlemek için önemli bir güvenlik önlemidir.

Bir örnek vermek gerekirse, ‘example.com’ gibi bir web sitesindeki bir JavaScript kodu, ‘api.example.com’ gibi bir farklı URL'den veri çağırmak istediğinde, CORS Header kullanılır. Bu header'ı kullanarak, API'nin farklı etki alanlarından gelen istekleri kabul etmesine izin verilir. Ancak, API sahibi özelleştirilmiş web sitelerinden gelen istekleri kabul etmek (allow) veya reddetmek (deny) konusunda kontrol sahibi olabilir.

Bununla birlikte, CORS Header API'ler arasında etkileşim sağlamak isteyen üçüncü taraf uygulamaları ve siteleri de etkileyebilir. Bu nedenle, API'yi kullanan geliştiriciler, API'lerinin CORS Header ayarlarını doğru bir şekilde yapılandırmalı ve güvenliği sağlamak için önlemler almalıdır.

Cache-Control Header

Cache-Control header, RESTful API'lerde yanıtların önbelleklenebilmesi için kullanılan bir header'dır. Bu header, API yanıtlarının önbelleklenmesine ilişkin kontrol ayarlarını belirler ve bunları açıklayan çeşitli parametreler içerebilir.

Cache-Control header, özellikle geniş ölçekli API'lerde kullanışlıdır. Bu tür API'lerde çok sayıda istek alındığı için önbellekleme işlemi, yanıtların daha hızlı ve daha verimli bir şekilde gönderilmesini sağlar. Ancak, yanıtların önbelleklenmesi bazı durumlarda istenmeyebilir ve yanlış sonuçlar üretir. Örneğin, API yanıtlarındaki veriler sık sık değiştiği için, önbelleklenmiş bir yanıt eski veya yanlış bilgiler içerebilir.

Cache-Control header'ın bazı parametreleri arasında max-age, no-cache, no-store, must-revalidate gibi özellikler yer alır. max-age özelliği, önbellekteki yanıtın ne kadar süreyle tutulacağını belirler. no-cache özelliği, yanıtların kesinlikle önbelleklenmemesi gerektiğini belirtir. no-store özelliği, yanıtların önbelleklerde saklanmaması gerektiğini belirtir. must-revalidate özelliği, önbellekteki yanıtın geçerlilik süresinin bittikten sonra yeniden doğrulanması gerektiğini belirtir.

Özet olarak, Cache-Control header, RESTful API'lerin performansını artırmak için yanıtların önbelleklenmesi ayarlarını belirleyen önemli bir HTTP header'dır. Ancak, yanlış kullanımları sonucunda istenmeyen sonuçlar üretebilir, bu nedenle öncelikle dikkatli bir şekilde değerlendirilmesi gerekir.

Max-Age Parametresi

Max-Age parametresi, HTTP önbellek kontrol başlığı olan Cache-Control header'ının bir parçasıdır. Bu header, API yanıtlarının önbellekte tutulabileceği süreyi belirleyen parametreler içerir. Max-Age parametresi, bu süreyi belirleyen en önemli parametrelerden biridir.

Max-Age parametresi, milisaniye cinsinden belirlenir ve önbellekte bulunacak içerik için kaç saniye geçerli olacağını belirler. Bu süre dolmadan önce yapılan istekler, önbellekteki veriye erişirler. Ancak süre dolduktan sonra veri yeniden API'den çekilir. Max-age parametresi, önbellekleme yaparken ne kadar süre saklanacağını belirlemek için önemlidir.

Bu header, önbellek süresi bitmeden önce önbellekten yeniden yükleme yapmamızı sağlayarak, API isteklerinin yanıt süresini kısaltmamıza yardımcı olur. Bu, site performansını arttırmak için önemlidir.

Örnek olarak, Max-Age parametresi 3600 (1 saat) olarak ayarlanmış bir API yanıtını düşünelim. İlk istek sırasında yanıt API'den alınacak ve önbelleklenerek saklanacaktır. İkinci bir istek, 1 saat içinde yapıldığında, yanıt tekrar API'den çekilmeden önbellekten yüklenir. Ancak 1 saat dolmuşsa, yeni bir istek API'ye gönderilir ve yanıt tekrar önbelleğe eklenir.

Max-Age parametresi özelleştirilebilir ve önbellek süresi, API'nin gereklerine göre ayarlanabilir. Ayrıca, saniye yerine "must-revalidate", "no-cache" veya "private" gibi farklı değerler de kullanılabilir. Bu, API geliştiricilerinin API performansını ve erişimini yönetmelerine olanak tanır.

User-Agent Header

API'lerin geliştirilmesinde oldukça önemli bir header olan User-Agent, API kullanıcıları hakkında bilgi toplamak veya istekleri farklı şekillerde yanıtlamak için kullanılır. User-Agent header'ı, istek yapan kullanıcının tarayıcısının tipini ve sürümünü belirtir. Bu sayede API, kullanıcının cihazına özel olarak yanıt verebilir ve kullanıcının isteklerine daha iyi karşılık verebilir.

Özellikle mobil cihaz kullanımında farklı tarayıcıların farklı User-Agent header'ları gönderebildiği düşünüldüğünde, API'lerin bu header'ı doğru bir şekilde okuyarak, mobil cihaz kullanıcılarına özel yanıt verebilmesi oldukça önemlidir. Örneğin, bir mobil uygulamadan API'ye gönderilen isteklerde, User-Agent header'ı mobil cihazın tipine ve işletim sistemine göre farklı değerler alabilir. Böylece API, mobil kullanıcılara özel olarak tasarlanmış bir arayüz sunabilir ve mobil cihazların özelliklerinden en iyi şekilde yararlanabilir.

Mobil Cihaz Kullanımı

Mobil cihazlar, farklı özelliklere ve sınırlamalara sahip olduklarından, API'ler genellikle mobil ve masaüstü cihazlar arasında farklı şekillerde istekleri yanıtlamak için kullanılır. Bu nedenle, API kullanıcılarının mobil cihazlarını doğru şekilde tanımlamak önemlidir.

Bunun için, User-Agent header kullanılır. Mobil bir cihazdan gönderilen isteklerin User-Agent header'ında, cihazın marka ve modeli hakkında bilgi bulunabilir. API bu bilgiyi kullanarak, mobil cihazlar için optimize edilmiş içerik veya arayüzler sağlayabilir.

Örnek User-Agent Header
Mozilla/5.0 (iPhone; CPU iPhone OS 12_1_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1

Yukarıdaki örnekte, kullanıcının bir iPhone'dan API'ye istek yaptığı belirtilir. Bu bilgiyi kullanan API, iPhone cihazlarında kullanılmak üzere optimize edilmiş bir arayüz sağlayabilir.

Accept Header

RESTful API'lerde kullanılan bir başka önemli HTTP header, Accept header'dır. Bu header, API'nin sunduğu farklı data formatlarını temsil eden mime-type'ların listesini belirtir.

API'nin sunduğu data formatları, XML, JSON, CSV, HTML, metin, resim, video, ve diğer birçok türde olabilir. Hangi formatın kullanılacağı, API kullanıcısına kalmıştır ve Accept header'ı kullanılarak belirtilir.

Bu header, API kullanıcısının talep ettiği data formatını sunucuya bildirerek, sunucunun doğru formatı sunmasını sağlar. Örneğin, bir mobil uygulama, API'den JSON veri formatında istekte bulunurken; bu uygulama, Accept: application/json header'ı ile bu talebinin JSON formatında olduğunu bildirir.

Bazı örnek Accept header değerleri şunlardır:

Header Değeri	Açıklama
Accept: application/json	JSON veri formatında istek yapmak için kullanılır.
Accept: application/xml	XML veri formatında istek yapmak için kullanılır.
Accept: text/html	HTML veri formatında istek yapmak için kullanılır.
Accept: text/csv	CSV veri formatında istek yapmak için kullanılır.

API sunucusu, Accept header'ı ile belirtilen değerleri desteklemiyorsa, HTTP status code 406 Not Acceptable yanıtını verebilir. Bu yanıt, sunucunun API kullanıcısından gelen talebi desteklemediğini belirtir.

HTML Data Türü

RESTful API'lerde, API'ye gönderilen veya API'den alınan verinin farklı türleri olabilir. Bu veri türünü belirtmek için Accept header kullanılır. Bu header, API tarafından sunulan farklı data formatlarını temsil eden mime-type'ların listesini belirtir. Örneğin, API tarafından sunulan HTML formatında veri için Accept header aşağıdaki gibi belirlenir:

Header Adı	Header Değeri
Accept	text/html

Bu header, API'ye istek gönderen kullanıcının HTML verisi almak istediğini belirtir. API, bu header değerine göre yanıt verecektir. Eğer API'den HTML verisi istenmiyorsa, istek kabul edilmeyebilir veya API farklı bir veri türü döndürebilir.

HTML verisi, genellikle belirli bir sayfanın veya belgenin görünümünü temsil eder ve API tarafından sunulan verilerin görsel olarak da sunulmasını sağlar. API kullanıcıları, HTML verisi ile görsel olarak temsil edilen verileri daha rahat anlayabilirler. Örneğin, bir raporun grafiklerle zenginleştirilmiş HTML hali, anlaşılması daha kolay olabilir.

CSV Data Türü

CSV (Comma Separated Values), gereksinim halinde kolayca anlaşılabilen bir veri formatıdır. API geliştiricileri tarafından kullanılırken, sıklıkla `Accept` başlığına CSV veritürünü de eklerler.

API kullanıcıları, `Accept` özelliğinde CSV'yi belirlediğinde API, verileri CSV biçiminde sunacaktır. CSV, kolayca düzenlenebilir, depolanabilir ve başka programlara aktarılabilir olması nedeniyle API'ler tarafından yaygın olarak kullanılır.

Başlık 1	Başlık 2	Başlık 3
Değer 1-1	Değer 1-2	Değer 1-3
Değer 2-1	Değer 2-2	Değer 2-3

Bir örnek kullanarak, bir API'den bir ülke listesi görüntüleyebilirsiniz. İstek aşağıdaki gibi olabilir:

GET /countries HTTP/1.1Host: api.ornek.comAccept: text/csv

API yanıtı aşağıdaki örnekteki gibi olabilir:

"Country","Capital","Population""Afghanistan","Kabul",27657145"Albania","Tirana",2886026"Algeria","Algiers",40400000"Andorra","Andorra la Vella",78014"Angola","Luanda",25868000

Bu basit bir örnektir ve çıktıda daha fazla sütun ve satır yer alabilir. CSV formatının esnekliği ve kullanım kolaylığı sayesinde, bu veriler daha sonra Excel gibi bir programda düzenlenebilir, analiz edilebilir ve daha fazla işleme tabi tutulabilir.