Web API Öğrenme Rehberi: Tarayıcı API'leri İçin Öğrenme Yolu

Web API nedir, JavaScript dilinden farkı ne?

Web API, tarayıcının (ve bazı durumlarda başka çalışma ortamlarının) JavaScript koduna sunduğu nesne ve fonksiyon kümesidir. MDN'in Web API dizini bunları iki biçimde listeler: belirli bir işi çözen API'ler (Fetch API, Web Storage API, Canvas API gibi) ve bu API'lerin kullandığı arayüzler, yani nesne türleri (Element, Response, Blob gibi). MDN, Web API'lerin çoğunlukla JavaScript ile kullanıldığını ama bunun zorunlu olmadığını da belirtir.

Burada önemli olan ayrım şudur: JavaScript dili; tipleri, operatörleri, fonksiyonları, sınıfları ve Promise gibi yerleşik nesneleri tanımlar. Sayfadaki bir başlığı değiştirmek, sunucuya istek göndermek veya tarayıcıda veri saklamak ise dilin değil, çalışma ortamının işidir. MDN'in DOM sayfası bunu açıkça söyler: DOM, JavaScript dilinin bir parçası değildir; web siteleri kurmak için kullanılan bir Web API'dir. Aynı JavaScript kodu Node.js'te de çalışabilir, ancak Node.js farklı bir API kümesi sunar ve DOM, Node.js çalışma zamanının çekirdek bir parçası değildir.

Bazı API'ler ise ortamdan bağımsızdır. EventTarget, Event, URL, TextEncoder, AbortController ve crypto.subtle gibi arayüzler WHATWG ve W3C standartlarında tanımlıdır ve Node.js de bunları aynı standarda göre uygular. Aşağıdaki kod hem tarayıcıda hem de Node.js 24 ile aynı biçimde çalışır; çıktıyı Node.js 24.4.0 ile çalıştırarak doğruladık:

const hedef = new EventTarget();
hedef.addEventListener("selam", (olay) => {
  console.log(olay.type);             // selam
  console.log(olay instanceof Event); // true
});
const sonuc = hedef.dispatchEvent(new Event("selam"));
console.log(sonuc);                   // true
console.log(typeof EventTarget);      // function

dispatchEvent() burada true döndürür, çünkü olay iptal edilmedi. Bu tür ortamdan bağımsız örnekleri serinin ilgili yazılarında Node.js ile çalıştırarak gösteriyoruz. document, window, çerezler, IndexedDB veya kamera gibi yalnızca tarayıcıda bulunan API'lerde ise örnekleri MDN belgelerine göre yazdık ve çıktı yorumunu yalnızca MDN sayfası o çıktıyı gösteriyorsa ekledik.

Bu seriyi hangi sırayla okumalısınız?

Aşağıdaki sekiz öğrenme yolu, birbirinin üzerine kurulan bir sıra izler. DOM temelleri olmadan olay delegasyonunu, olaylar olmadan form gönderimini, Promise ve fetch olmadan service worker önbelleklemesini anlamak zordur. Yeni başlıyorsanız ilk iki yolu sırayla okuyun; sonrasında ihtiyacınıza göre ağ, depolama veya PWA yoluna geçebilirsiniz. HTTP ve güvenlik yolunu ise ağ istekleri yolunu bitirdikten sonra okumanızı öneririz, çünkü CORS ve önbellek başlıkları orada öğrendiğiniz kavramlara dayanır.

1. DOM temelleri

Sayfanın JavaScript tarafından nasıl görüldüğünü, öğelerin nasıl bulunduğunu, oluşturulduğunu ve değiştirildiğini anlatan temel yazılar:

• DOM nedir?: Belgenin düğüm ağacı olarak nasıl temsil edildiğini, Node, Element, Document ve window arasındaki ilişkiyi anlatır.
• querySelector ve getElementById ile öğe seçme: Kimlik, sınıf, etiket ve CSS seçiciyle öğe bulmayı, canlı ve statik koleksiyon farkını gösterir.
• DOM'da öğe oluşturma, ekleme ve silme: createElement, append, before, remove, cloneNode ve DocumentFragment kullanımını işler.
• innerHTML, textContent ve innerText farkı: Öğe içeriğini okumanın ve yazmanın yollarını, HTML ayrıştırmanın güvenlik etkisini karşılaştırır.
• classList, setAttribute ve style: Öznitelik ile özellik arasındaki yansıtma ilişkisini, sınıf listesini ve satır içi stilleri anlatır.
• DOM ağacında gezinme: Ebeveyn, çocuk ve kardeş düğümlere geçmeyi, NodeList ile HTMLCollection farkını ve TreeWalker kullanımını gösterir.

2. Olaylar ve formlar

Kullanıcının tıklamasına, tuşa basmasına veya formu göndermesine tepki vermeyi öğreten yazılar:

• addEventListener ile olay dinleme: once, passive, capture ve signal seçeneklerini, dinleyiciyi kaldırmayı ve Event nesnesini açıklar.
• Olay kabarcıklanması, yakalama ve delegasyon: Olayın ağaçta hangi evrelerden geçtiğini, stopPropagation ve preventDefault farkını, delegasyon desenini anlatır.
• Klavye olayları: keydown ve keyup olaylarını, key ile code farkını, tekrar ve IME bileşimini ele alır.
• Pointer olayları: Fare, kalem ve dokunmatik girdiyi tek modelle işlemeyi, pointerType ve işaretçi yakalamayı gösterir.
• CustomEvent ve EventTarget: Kendi olaylarınızı detail verisiyle oluşturup göndermeyi ve EventTarget tabanlı sınıf yazmayı anlatır.
• Sayfa yaşam döngüsü olayları: DOMContentLoaded, load, visibilitychange, pagehide ve sendBeacon ile sayfanın açılış ve kapanış anlarını yönetmeyi işler.
• Form gönderme ve FormData: submit olayını, FormData nesnesini ve requestSubmit kullanımını JavaScript tarafından anlatır.

3. Ağ istekleri ve CORS

Sunucuyla veri alışverişi yapan API'ler ve tarayıcının farklı kökenler arasındaki istekleri nasıl denetlediği:

• Fetch API ile GET ve POST isteği: fetch() çağrısını, response.ok kontrolünü, JSON gövdeleri ve hata yakalamayı tarayıcı açısından anlatır.
• Request, Response ve Headers nesneleri: İstek ve yanıt nesnelerini, gövdenin yalnızca bir kez okunabilmesini ve clone() kullanımını işler.
• CORS nedir?: Aynı köken ilkesini, basit istekleri, ön uçuş (preflight) isteğini ve Access-Control-Allow-* başlıklarını açıklar.
• CORS hataları ve çözümleri: MDN'in listelediği CORS hata mesajlarını tek tek ele alıp nedenlerini ve çözümlerini verir.
• WebSocket API kullanımı: Tarayıcı tarafında WebSocket bağlantısı açmayı, mesaj göndermeyi ve bağlantı kapanış kodlarını gösterir.
• XMLHttpRequest ve fetch farkı: Eski XHR arayüzünü, readyState ve ilerleme olaylarını, fetch ile farklarını karşılaştırır.

4. Depolama ve dosyalar

Tarayıcıda veri saklama yöntemleri ve kullanıcının seçtiği dosyaları okuma:

• localStorage ve sessionStorage: Web Storage API ile anahtar ve değer saklamayı, storage olayını ve kota hatasını anlatır.
• document.cookie ve Set-Cookie özellikleri: Çerezleri JavaScript ile okuyup yazmayı ve Secure, HttpOnly, SameSite gibi özellikleri teknik açıdan işler.
• IndexedDB kullanımı: Veritabanı açmayı, nesne deposu, işlem (transaction), indeks ve imleç kavramlarını adım adım gösterir.
• Cache API kullanımı: caches.open ile önbellek açmayı, yanıt eklemeyi, eşleştirmeyi ve silmeyi anlatır.
• Storage API ve depolama kotası: navigator.storage.estimate() ve persist() ile kotayı ve kalıcı depolamayı ele alır.
• File API, FileReader ve Blob: Kullanıcının seçtiği veya sürüklediği dosyaları okumayı ve nesne URL'si oluşturmayı gösterir.

5. Arka plan, PWA ve iletişim

Ana iş parçacığının dışında çalışan kod, çevrimdışı çalışma ve sayfalar arası mesajlaşma:

• Web Workers ve postMessage: Ayrı bir iş parçacığında kod çalıştırmayı, mesajlaşmayı ve aktarılabilir nesneleri anlatır.
• Service worker kaydı ve yaşam döngüsü: Service worker kaydetmeyi, kapsamı, install ve activate evrelerini ve güncellemeyi işler.
• Service worker ile çevrimdışı önbellek stratejileri: fetch olayını yakalayıp önce önbellek, önce ağ gibi stratejileri uygulamayı gösterir.
• PWA nedir ve web app manifest: İlerleyen web uygulaması kavramını, manifest üyelerini ve kurulabilirliği açıklar.
• Notifications API ve bildirim izni: Bildirim izni istemeyi ve sistem bildirimi göstermeyi anlatır.
• window.postMessage ile iframe ve sekme iletişimi: Pencereler arası güvenli mesajlaşmayı, köken kontrolünü, MessageChannel ve BroadcastChannel kullanımını işler.

6. Gözlemciler, çizim ve medya

Sayfadaki değişiklikleri izleyen gözlemciler, animasyon döngüsü, canvas ve kamera erişimi:

• Intersection Observer: Bir öğenin görünür alana girip çıkmasını izlemeyi, eşik ve kök kenar boşluğu ayarlarını gösterir.
• ResizeObserver ve MutationObserver: Öğe boyutu ve DOM değişikliklerini izlemeyi, gözlemciyi durdurmayı anlatır.
• requestAnimationFrame ile animasyon döngüsü: Ekran yenilemesiyle uyumlu animasyon yazmayı ve zaman damgasını kullanmayı işler.
• Canvas API çizim rehberi: 2D bağlam ile şekil, yol, renk, metin ve dönüşüm çizmeyi gösterir.
• Canvas ile görsel ve piksel işlemleri: Görsel çizmeyi, piksel verisini okuyup yazmayı ve canvas içeriğini dosyaya dönüştürmeyi anlatır.
• getUserMedia ile kamera ve mikrofon: Medya akışı istemeyi, kısıtlamaları, izin hatalarını ve kayıt almayı ele alır.

7. Diğer tarayıcı API'leri

Tek sayfa uygulamalarda yönlendirme, pano, konum, şifreleme, performans ölçümü ve kendi HTML öğelerinizi tanımlama:

• History API ile SPA yönlendirme: pushState, replaceState ve popstate ile adres çubuğunu yönetmeyi anlatır.
• Clipboard API ile panoya kopyalama: Metin ve veri kopyalayıp yapıştırmayı, izin ve kullanıcı etkinliği şartlarını işler.
• Geolocation API ile konum alma: Anlık konum almayı, konumu izlemeyi, seçenekleri ve hata kodlarını gösterir.
• Web Crypto API: Rastgele değer üretmeyi, özet (hash) almayı ve AES-GCM ile şifreleyip çözmeyi anlatır.
• Performance API ile sayfa performansı ölçme: performance.now, işaret ve ölçüm oluşturmayı, PerformanceObserver kullanımını işler.
• Web Components, custom elements ve shadow DOM: Kendi öğenizi tanımlamayı, yaşam döngüsü geri çağrılarını ve shadow DOM eklemeyi gösterir.

8. HTTP, güvenlik ve hatalar

Tarayıcı ile sunucu arasındaki protokol katmanı, yaygın saldırılara karşı savunmalar ve Web API hata türleri:

• HTTP Cache-Control, ETag ve koşullu istekler: Önbellek yönergelerini, doğrulayıcıları ve 304 yanıtının nasıl oluştuğunu başlık düzeyinde anlatır.
• HTTP istek ve yanıt yapısı: HTTP mesajının bölümlerini ve GET, POST, PUT, PATCH, DELETE gibi metotların anlamını açıklar.
• CSRF saldırısı ve korunma: Siteler arası istek sahteciliğini, belirteçleri, SameSite çerezleri ve Fetch Metadata başlıklarını işler.
• Clickjacking, X-Frame-Options ve frame-ancestors: Sayfanızın başka bir sitede çerçeve içine alınmasını engellemeyi anlatır.
• Passkey ve WebAuthn ile şifresiz giriş: Passkey kavramını ve WebAuthn ile kayıt ve giriş akışını gösterir.
• DOMException ve güvenli bağlam hataları: NotAllowedError, SecurityError gibi hata adlarını, güvenli bağlam ve kullanıcı etkinliği şartlarını açıklar.

MDN'de bir API sayfası nasıl okunur?

Bu serideki her yazı MDN'deki arayüz ve üye sayfalarına bağlantı verir. Bu sayfalar belli bir düzenle yazılmıştır; düzeni bir kez öğrendiğinizde aradığınızı çok daha hızlı bulursunuz. Bir arayüz sayfası (örneğin Element) genellikle şu bölümlerden oluşur:

• Kısa tanım: Arayüzün neyi temsil ettiği ve hangi arayüzlerin ondan türediği. Element sayfası, HTML öğelerinin HTMLElement, SVG öğelerinin SVGElement üzerinden Element'ten türediğini söyler.
• Constructor (yapıcı): Nesneyi new ile oluşturabiliyorsanız burada yazar. DocumentFragment() veya Event() gibi. Element gibi bazı arayüzlerin doğrudan yapıcısı yoktur; nesneyi document.createElement() gibi bir fabrika metoduyla alırsınız.
• Static properties / static methods: Nesne örneği yerine arayüzün kendisi üzerinden çağrılan üyeler, örneğin CSS.escape().
• Instance properties (örnek özellikleri): Nesne üzerinden okuduğunuz veya yazdığınız değerler. Salt okunur olanlar ayrıca belirtilir.
• Instance methods (örnek metotları): Nesne üzerinden çağırdığınız fonksiyonlar.
• Events (olaylar): Bu arayüzün tetiklediği olaylar. MDN, bunları addEventListener() ile veya oneventname özelliğine atama yaparak dinleyebileceğinizi belirtir.

Kalıtım bu sayfaları okurken en sık gözden kaçan noktadır. Element sayfasının özellikler bölümü, Element'in özelliklerini üst arayüzü Node'dan, onun da üst arayüzü EventTarget'tan devraldığını yazar. Yani bir <button> nesnesinde addEventListener() (EventTarget), appendChild() (Node), querySelector() (Element), focus() (HTMLElement) ve disabled (HTMLButtonElement) aynı anda bulunur. Aradığınız üye bir sayfada yoksa üst arayüzün sayfasına bakın.

Üye sayfalarının (örneğin Element.closest()) düzeni de sabittir: Syntax bölümü çağrı biçimini, Parameters her parametrenin anlamını ve isteğe bağlı olup olmadığını, Return value dönen değeri, Exceptions hangi durumda hangi DOMException adının fırlatıldığını gösterir. Ardından Examples gelir. Sayfanın sonundaki Browser compatibility tablosu her tarayıcıdaki desteği gösterir; bu tablo serinin kaynak aldığı yerel kopyada bulunmadığı için yazılarda destek oranı veya sürüm numarası vermiyoruz. Bir özelliği kullanmadan önce canlı MDN sayfasındaki uyumluluk tablosuna bakmanızı öneririz.

Güvenli bağlam, izin ve kullanıcı etkinliği ne demek?

Bazı Web API'leri her sayfada çalışmaz. MDN üç tür kısıtlamadan söz eder ve ilgili API sayfaları hangisinin geçerli olduğunu belirtir. Bunları baştan bilmek, "kod neden çalışmıyor" sorusunun yanıtını çoğu zaman hemen verir.

Güvenli bağlam (secure context): Kimlik doğrulama ve gizlilik açısından belirli bir standardı karşılayan pencere veya worker ortamıdır. MDN'e göre kabaca, kaynakları HTTPS ile veya yerel geri döngü (loopback) adresinden sunulan belgeler güvenli bağlamdır; http://localhost ve file:// adresleri de güvenli sayılır, http://example.com ise sayılmaz. Bir <iframe> içindeki belgenin güvenli bağlam olması için hem kendi adresinin hem de onu gömen belgenin güvenli olması gerekir. Service worker yalnızca güvenli bağlamdan kaydedilebilir. Kodunuzun güvenli bağlamda olup olmadığını window.isSecureContext özelliği true veya false olarak bildirir. Sitenizi HTTPS'e taşımak için HTTPS ve TLS 1.3 rehberi ve karma içerik hatası çözümü yazılarına bakabilirsiniz.

İzin (permission): Konum, bildirim, pano okuma veya kamera gibi güçlü API'ler kullanıcıdan izin ister. Permissions API, navigator.permissions.query() ile bir iznin durumunu sorgulamanızı sağlar; dönen durum granted, prompt veya denied olabilir. MDN, bu durumun güvenli bağlam şartı, Permissions-Policy kısıtlamaları ve kullanıcı istemleri dahil bağlamdaki tüm güvenlik kısıtlamalarını bir arada yansıttığını belirtir. İzin isteme penceresinin nasıl açılacağı ise her API'nin kendi metoduna bağlıdır.

navigator.permissions.query({ name: "geolocation" }).then((result) => {
  if (result.state === "granted") {
    // konuma dayalı içeriği göster
  } else if (result.state === "prompt") {
    // kullanıcıya izin vermesi için bir düğme göster
  }
  // "denied" durumunda hiçbir şey yapma
});

Kullanıcı etkinliği (user activation): Açılır pencere, tam ekran veya pano yazma gibi kötüye kullanılabilecek özellikler, kullanıcının sayfayla gerçekten etkileşime girmesini şart koşar. MDN iki türü ayırır: geçici etkinlik (transient activation) kısa süre geçerlidir ve bazı API'ler tarafından tüketilebilir; kalıcı etkinlik (sticky activation) ise oturum boyunca sürer. Etkinliği tetikleyen olaylar arasında keydown, mousedown, fareyle yapılan pointerdown, fare dışı girdilerde pointerup ve touchend sayılır ve olayın isTrusted değerinin true olması gerekir. Clipboard.writeText() geçici etkinlik isteyen API'lerden biridir; bu yüzden sayfa yüklenir yüklenmez değil, bir düğme tıklamasının içinde çağrılmalıdır.

Bu üç kısıtlamanın ihlali genellikle bir DOMException ile sonuçlanır. Hangi durumda NotAllowedError, hangi durumda SecurityError aldığınızı ve bunları nasıl ayırt edeceğinizi DOMException ve güvenli bağlam hataları yazısında ayrıntılı anlattık.

Web API öğrenirken sık yapılan hatalar

• Dil ile API'yi karıştırmak: document veya localStorage Node.js'te tanımlı değildir. Tarayıcı kodunu Node.js'te çalıştırıp hata aldığınızda sorun kodda değil, ortamdadır.
• Kalıtımı unutmak: Bir özelliği HTMLInputElement sayfasında bulamadığınızda HTMLElement, Element ve Node sayfalarına bakmamak.
• Uyumluluk tablosuna bakmamak: Yeni bir API'nin her tarayıcıda olduğunu varsaymak. Özellik algılama ("clipboard" in navigator gibi) ve MDN tablosu birlikte kullanılmalıdır.
• HTTP üzerinde test etmek: Güvenli bağlam isteyen bir API'yi düz HTTP ile yayınlanan bir sunucuda denemek. Yerel geliştirmede localhost güvenli sayılır, ancak canlı sitede HTTPS gerekir.
• Hata adlarını yok saymak: catch içinde yalnızca "hata oluştu" yazmak. DOMException nesnesinin name değeri sorunun türünü doğrudan söyler.

Sık Sorulan Sorular

Web API öğrenmek için hangi JavaScript bilgisi gerekir?

Fonksiyonlar, nesneler, diziler ve olay dinleyicilerinde kullanılan ok fonksiyonları yeterli bir başlangıçtır. Ağ ve depolama API'leri Promise döndürdüğü için async/await konusunu da bilmeniz gerekir. Kodun ne zaman çalıştığını anlamak için JavaScript olay döngüsü yazısı da faydalıdır.

DOM ile HTML aynı şey mi?

Hayır. HTML, sunucudan gelen metin biçimindeki kaynaktır; DOM ise tarayıcının bu kaynağı ayrıştırarak bellekte kurduğu nesne ağacıdır. JavaScript HTML metnini değil, DOM'u değiştirir. Ayrıntılar DOM nedir yazısında.

Bir API'nin tarayıcımda olup olmadığını nasıl anlarım?

İki yol vardır: Canlı MDN sayfasındaki Browser compatibility tablosuna bakmak ve kodda özellik algılama yapmak, yani API'yi kullanmadan önce ilgili nesnenin veya metodun var olup olmadığını kontrol etmek. Bu seri yerel bir MDN kopyasına dayandığı için destek bilgisi vermiyor; her yazıda uyumluluk tablosuna yönlendiriyoruz.

Bu yazılardaki örnekler çalıştırılarak mı denendi?

Tarayıcıdan bağımsız standart API örnekleri (EventTarget, Request, Response, Blob, TextEncoder, crypto.subtle gibi) Node.js 24.4.0 ile çalıştırılarak denendi ve çıktı yorumları gerçek çıktıyla eşleştirildi. DOM ve diğer tarayıcıya özgü örnekler MDN belgelerine göre yazıldı; bunlarda çıktı yorumunu yalnızca MDN sayfası o çıktıyı gösteriyorsa verdik.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: JavaScript öğrenme rehberi · HTML öğrenme rehberi · DOM nedir · Fetch API kullanımı · DOMException ve güvenli bağlam hataları