TypeScript ile Tür Güvenli API Çağrıları: Kapsamlı Bir Rehber

Modern web geliştirmede, API'lerle etkileşim temel bir görevdir. TypeScript, güçlü tür sistemiyle, tür güvenli API çağrılarını etkinleştirerek uygulamalarınızın güvenilirliğini ve sürdürülebilirliğini sağlamada önemli bir avantaj sunar. Bu kılavuz, en iyi uygulamaları, gelişmiş teknikleri ve gerçek dünya örneklerini kapsayarak, sağlam ve hatasız API etkileşimleri oluşturmak için TypeScript'in özelliklerinden nasıl yararlanabileceğinizi keşfedecektir.

API Çağrıları İçin Neden Tür Güvenliği Önemlidir

API'lerle çalışırken, esasen harici bir kaynaktan gelen verilerle uğraşırsınız. Bu veriler her zaman beklediğiniz biçimde olmayabilir ve bu da çalışma zamanı hatalarına ve beklenmedik davranışlara yol açabilir. Tür güvenliği, aldığınız verilerin önceden tanımlanmış bir yapıya uygun olduğunu doğrulayarak, potansiyel sorunları geliştirme sürecinin başlarında yakalayarak kritik bir koruma katmanı sağlar.

• Azaltılmış Çalışma Zamanı Hataları: Derleme zamanında tür denetimi, türle ilgili hataları üretime ulaşmadan önce tanımlamaya ve düzeltmeye yardımcı olur.
• Geliştirilmiş Kod Sürdürülebilirliği: Açık tür tanımları, kodunuzu anlamayı ve değiştirmeyi kolaylaştırır ve yeniden düzenleme sırasında hataların ortaya çıkma riskini azaltır.
• Gelişmiş Kod Okunabilirliği: Tür açıklamaları, beklenen veri yapılarını anlamayı geliştiriciler için kolaylaştırarak değerli belgeler sağlar.
• Daha İyi Geliştirici Deneyimi: Tür denetimi ve otomatik tamamlama için IDE desteği, geliştirici deneyimini önemli ölçüde iyileştirir ve hata olasılığını azaltır.

TypeScript Projenizi Ayarlama

API çağrılarına dalmadan önce, bir TypeScript projesi kurduğunuzdan emin olun. Sıfırdan başlıyorsanız, yeni bir projeyi şu şekilde başlatabilirsiniz:

npm init -y
npm install typescript --save-dev
tsc --init

Bu, varsayılan TypeScript derleyici seçenekleriyle bir `tsconfig.json` dosyası oluşturacaktır. Bu seçenekleri projenizin ihtiyaçlarına göre özelleştirebilirsiniz. Örneğin, daha katı tür denetimi için katı modu etkinleştirmek isteyebilirsiniz:

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

API Yanıtları İçin Türleri Tanımlama

Tür güvenli API çağrıları elde etmede ilk adım, API'den almayı beklediğiniz verilerin yapısını temsil eden TypeScript türlerini tanımlamaktır. Bu genellikle `interface` veya `type` bildirimleri kullanılarak yapılır.

Arayüzleri Kullanma

Arayüzler, bir nesnenin şeklini tanımlamanın güçlü bir yoludur. Örneğin, bir API'den bir kullanıcı listesi getiriyorsanız, şöyle bir arayüz tanımlayabilirsiniz:

interface User {
  id: number;
  name: string;
  email: string;
  address?: string; // İsteğe bağlı özellik
  phone?: string; // İsteğe bağlı özellik
  website?: string; // İsteğe bağlı özellik
  company?: {
    name: string;
    catchPhrase: string;
    bs: string;
  };
}

Bir özellik adından sonraki `?`, özelliğin isteğe bağlı olduğunu gösterir. Bu, belirli alanların eksik olabileceği API yanıtlarını işlemek için kullanışlıdır.

Türleri Kullanma

Türler arayüzlere benzer, ancak birleşim türlerini ve kesişim türlerini tanımlama yeteneği de dahil olmak üzere daha fazla esneklik sunar. Bir tür kullanarak yukarıdaki arayüzle aynı sonucu elde edebilirsiniz:

type User = {
  id: number;
  name: string;
  email: string;
  address?: string; // İsteğe bağlı özellik
  phone?: string; // İsteğe bağlı özellik
  website?: string; // İsteğe bağlı özellik
  company?: {
    name: string;
    catchPhrase: string;
    bs: string;
  };
};

Basit nesne yapıları için arayüzler ve türler genellikle birbirinin yerine kullanılabilir. Ancak, türler daha karmaşık senaryolarla uğraşırken daha güçlü hale gelir.

Axios ile API Çağrıları Yapma

Axios, JavaScript ve TypeScript'te API istekleri yapmak için popüler bir HTTP istemcisidir. Farklı HTTP yöntemlerini, istek başlıklarını ve yanıt verilerini işlemeyi kolaylaştıran temiz ve sezgisel bir API sağlar.

Axios'u Yükleme

npm install axios

Türlü Bir API Çağrısı Yapma

Axios ile tür güvenli bir API çağrısı yapmak için `axios.get` yöntemini kullanabilir ve jenerikleri kullanarak beklenen yanıt türünü belirtebilirsiniz:

import axios from 'axios';

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    return response.data;
  } catch (error) {
    console.error('Kullanıcılar alınırken hata:', error);
    throw error;
  }
}

fetchUsers().then(users => {
  users.forEach(user => {
    console.log(user.name);
  });
});

Bu örnekte, `axios.get('...')` TypeScript'e yanıt verilerinin `User` nesneleri dizisi olması gerektiğini söyler. Bu, TypeScript'in yanıt verileriyle çalışırken tür denetimi ve otomatik tamamlama sağlamasına olanak tanır.

Farklı HTTP Yöntemlerini İşleme

Axios, `GET`, `POST`, `PUT`, `DELETE` ve `PATCH` dahil olmak üzere çeşitli HTTP yöntemlerini destekler. Farklı API istek türleri yapmak için karşılık gelen yöntemleri kullanabilirsiniz. Örneğin, yeni bir kullanıcı oluşturmak için `axios.post` yöntemini kullanabilirsiniz:

async function createUser(user: Omit): Promise {
  try {
    const response = await axios.post('https://jsonplaceholder.typicode.com/users', user);
    return response.data;
  } catch (error) {
    console.error('Kullanıcı oluşturulurken hata:', error);
    throw error;
  }
}

const newUser = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  address: '123 Main St',
  phone: '555-1234',
  website: 'example.com',
  company: {
    name: 'Example Corp',
    catchPhrase: 'Yol gösteriyor',
    bs: 'Yenilikçi çözümler'
  }
};

createUser(newUser).then(user => {
  console.log('Oluşturulan kullanıcı:', user);
});

Bu örnekte, `Omit`, `User` ile aynı olan ancak `id` özelliği olmayan bir tür oluşturur. Bu, `id` genellikle yeni bir kullanıcı oluşturulurken sunucu tarafından oluşturulduğu için kullanışlıdır.

Fetch API'sini Kullanma

Fetch API, HTTP istekleri yapmak için yerleşik bir JavaScript API'sidir. Axios'tan daha temel olsa da, tür güvenli API çağrıları elde etmek için TypeScript ile de kullanılabilir. İhtiyaçlarınıza uyuyorsa bir bağımlılık eklemekten kaçınmak için bunu tercih edebilirsiniz.

Fetch ile Türlü Bir API Çağrısı Yapma

Fetch ile tür güvenli bir API çağrısı yapmak için `fetch` işlevini kullanabilir ve ardından yanıtı JSON olarak ayrıştırabilir ve beklenen yanıt türünü belirtebilirsiniz:

async function fetchUsers(): Promise {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
    if (!response.ok) {
      throw new Error(`HTTP hatası! durum: ${response.status}`);
    }
    const data: User[] = await response.json();
    return data;
  } catch (error) {
    console.error('Kullanıcılar alınırken hata:', error);
    throw error;
  }
}

fetchUsers().then(users => {
  users.forEach(user => {
    console.log(user.name);
  });
});

Bu örnekte, `const data: User[] = await response.json();` TypeScript'e yanıt verilerinin `User` nesneleri dizisi olarak ele alınması gerektiğini söyler. Bu, TypeScript'in tür denetimi ve otomatik tamamlama gerçekleştirmesine olanak tanır.

Fetch ile Farklı HTTP Yöntemlerini İşleme

Fetch ile farklı API istek türleri yapmak için `fetch` işlevini `method` ve `body` seçenekleri gibi farklı seçeneklerle kullanabilirsiniz. Örneğin, yeni bir kullanıcı oluşturmak için aşağıdaki kodu kullanabilirsiniz:

async function createUser(user: Omit): Promise {
  try {
    const response = await fetch('https://jsonplaceholder.typicode.com/users', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(user)
    });
    if (!response.ok) {
      throw new Error(`HTTP hatası! durum: ${response.status}`);
    }
    const data: User = await response.json();
    return data;
  } catch (error) {
    console.error('Kullanıcı oluşturulurken hata:', error);
    throw error;
  }
}

const newUser = {
  name: 'John Doe',
  email: 'john.doe@example.com',
  address: '123 Main St',
  phone: '555-1234',
  website: 'example.com',
  company: {
    name: 'Example Corp',
    catchPhrase: 'Yol gösteriyor',
    bs: 'Yenilikçi çözümler'
  }
};

createUser(newUser).then(user => {
  console.log('Oluşturulan kullanıcı:', user);
});

API Hatalarını İşleme

Hata işleme, API çağrılarının kritik bir yönüdür. API'ler, ağ bağlantısı sorunları, sunucu hataları ve geçersiz istekler dahil olmak üzere birçok nedenden dolayı başarısız olabilir. Uygulamanızın çökmesini veya beklenmedik davranışlar görüntülemesini önlemek için bu hataları zarifçe işlemek önemlidir.

Try-Catch Bloklarını Kullanma

Asenkron kodda hataları işlemenin en yaygın yolu, try-catch bloklarını kullanmaktır. Bu, API çağrısı sırasında oluşan istisnaları yakalamanıza ve bunları uygun şekilde işlemenize olanak tanır.

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    return response.data;
  } catch (error) {
    console.error('Kullanıcılar alınırken hata:', error);
    // Hatayı işleyin, örneğin, kullanıcıya bir hata mesajı görüntüleyin
    throw error; // Çağıran kodun da işlemesine izin vermek için hatayı yeniden atın
  }
}

Belirli Hata Kodlarını İşleme

API'ler genellikle meydana gelen hata türünü belirtmek için belirli hata kodları döndürür. Daha özel hata işleme sağlamak için bu hata kodlarını kullanabilirsiniz. Örneğin, bir 404 Bulunamadı hatası için 500 Dahili Sunucu Hatası'ndan farklı bir hata mesajı görüntülemek isteyebilirsiniz.

async function fetchUser(id: number): Promise {
  try {
    const response = await axios.get(`https://jsonplaceholder.typicode.com/users/${id}`);
    return response.data;
  } catch (error: any) {
    if (error.response?.status === 404) {
      console.log(`ID ${id} olan kullanıcı bulunamadı.`);
      return null; // Veya özel bir hata atın
    } else {
      console.error('Kullanıcı alınırken hata:', error);
      throw error;
    }
  }
}

fetchUser(123).then(user => {
  if (user) {
    console.log('Kullanıcı:', user);
  } else {
    console.log('Kullanıcı bulunamadı.');
  }
});

Özel Hata Türleri Oluşturma

Daha karmaşık hata işleme senaryoları için, farklı API hata türlerini temsil etmek üzere özel hata türleri oluşturabilirsiniz. Bu, daha yapılandırılmış hata bilgileri sağlamanıza ve hataları daha etkili bir şekilde işlemenize olanak tanır.

class ApiError extends Error {
  constructor(public statusCode: number, message: string) {
    super(message);
    this.name = 'ApiError';
  }
}

async function fetchUser(id: number): Promise {
  try {
    const response = await axios.get(`https://jsonplaceholder.typicode.com/users/${id}`);
    return response.data;
  } catch (error: any) {
    if (error.response?.status === 404) {
      throw new ApiError(404, `ID ${id} olan kullanıcı bulunamadı.`);
    } else {
      console.error('Kullanıcı alınırken hata:', error);
      throw new ApiError(500, 'Dahili Sunucu Hatası'); //Veya uygun başka bir durum kodu
    }
  }
}

fetchUser(123).catch(error => {
  if (error instanceof ApiError) {
    console.error(`API Hatası: ${error.statusCode} - ${error.message}`);
  } else {
    console.error('Beklenmedik bir hata oluştu:', error);
  }
});

Veri Doğrulama

TypeScript'in tür sistemiyle bile, API'lerden aldığınız verileri çalışma zamanında doğrulamak çok önemlidir. API'ler yanıt yapılarını haber vermeden değiştirebilir ve TypeScript türleriniz her zaman API'nin gerçek yanıtıyla mükemmel şekilde senkronize olmayabilir.

Çalışma Zamanı Doğrulaması İçin Zod'u Kullanma

Zod, çalışma zamanı veri doğrulaması için popüler bir TypeScript kitaplığıdır. Verilerinizin beklenen yapısını açıklayan şemalar tanımlamanıza ve ardından verileri çalışma zamanında bu şemalara göre doğrulamanıza olanak tanır.

Zod'u Yükleme

npm install zod

API Yanıtlarını Zod ile Doğrulama

API yanıtlarını Zod ile doğrulamak için, TypeScript türünüze karşılık gelen bir Zod şeması tanımlayabilir ve ardından verileri doğrulamak için `parse` yöntemini kullanabilirsiniz.

import { z } from 'zod';

const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  address: z.string().optional(),
  phone: z.string().optional(),
  website: z.string().optional(),
  company: z.object({
    name: z.string(),
    catchPhrase: z.string(),
    bs: z.string(),
  }).optional(),
});

type User = z.infer;

async function fetchUsers(): Promise {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/users');
    const data = z.array(userSchema).parse(response.data);
    return data;
  } catch (error) {
    console.error('Kullanıcılar alınırken hata:', error);
    throw error;
  }
}

Bu örnekte, `z.array(userSchema).parse(response.data)`, yanıt verilerinin `userSchema`'ya uygun nesneler dizisi olduğunu doğrular. Veriler şemaya uymuyorsa, Zod bir hata atar ve bu hatayı daha sonra uygun şekilde işleyebilirsiniz.

Gelişmiş Teknikler

Yeniden Kullanılabilir API İşlevleri İçin Jenerikler Kullanma

Jenerikler, farklı veri türlerini işleyebilen yeniden kullanılabilir API işlevleri yazmanıza olanak tanır. Örneğin, herhangi bir API uç noktasından veri getirebilen ve doğru türle döndürebilen genel bir `fetchData` işlevi oluşturabilirsiniz.

async function fetchData(url: string): Promise {
  try {
    const response = await axios.get(url);
    return response.data;
  } catch (error) {
    console.error(`${url} adresinden veri alınırken hata:`, error);
    throw error;
  }
}

// Kullanım
fetchData('https://jsonplaceholder.typicode.com/users').then(users => {
  console.log('Kullanıcılar:', users);
});

fetchData<{ title: string; body: string }>('https://jsonplaceholder.typicode.com/todos/1').then(todo => {
    console.log('Yapılacaklar', todo)
});

Global Hata İşleme İçin Önleyicileri Kullanma

Axios, kodunuz tarafından işlenmeden önce istekleri ve yanıtları engellemenize olanak tanıyan önleyiciler sağlar. Hataları günlüğe kaydetme veya kullanıcıya hata mesajları görüntüleme gibi genel hata işlemeyi uygulamak için önleyicileri kullanabilirsiniz.

axios.interceptors.response.use(
  (response) => response,
  (error) => {
    console.error('Global hata işleyici:', error);
    // Kullanıcıya bir hata mesajı görüntüleyin
    return Promise.reject(error);
  }
);

API URL'leri İçin Ortam Değişkenlerini Kullanma

Kodunuzda API URL'lerini sabit kodlamaktan kaçınmak için, URL'leri depolamak üzere ortam değişkenlerini kullanabilirsiniz. Bu, uygulamanızı geliştirme, hazırlama ve üretim gibi farklı ortamlar için yapılandırmayı kolaylaştırır.

`.env` dosyası ve `dotenv` paketi kullanarak örnek.

// .env
API_URL=https://api.example.com

// dotenv'i yükleyin
npm install dotenv

// dotenv'i içe aktarın ve yapılandırın
import * as dotenv from 'dotenv'
dotenv.config()

const apiUrl = process.env.API_URL || 'http://localhost:3000'; // varsayılan bir değer sağlayın

async function fetchData(endpoint: string): Promise {
  try {
    const response = await axios.get(`${apiUrl}/${endpoint}`);
    return response.data;
  } catch (error) {
    console.error(`${apiUrl}/${endpoint} adresinden veri alınırken hata:`, error);
    throw error;
  }
}

Sonuç

Tür güvenli API çağrıları, sağlam, sürdürülebilir ve hatasız web uygulamaları oluşturmak için gereklidir. TypeScript, API yanıtları için türler tanımlamanıza, verileri çalışma zamanında doğrulamanıza ve hataları zarifçe işlemenize olanak tanıyan güçlü özellikler sağlar. Bu kılavuzda özetlenen en iyi uygulamaları ve teknikleri izleyerek, API etkileşimlerinizin kalitesini ve güvenilirliğini önemli ölçüde artırabilirsiniz.

TypeScript ve Axios ve Zod gibi kitaplıkları kullanarak, API çağrılarınızın tür güvenli, verilerinizin doğrulandığından ve hatalarınızın zarifçe işlendiğinden emin olabilirsiniz. Bu, daha sağlam ve sürdürülebilir uygulamalara yol açacaktır.

TypeScript'in tür sistemiyle bile, verilerinizi her zaman çalışma zamanında doğrulamayı unutmayın. API'ler değişebilir ve türleriniz her zaman API'nin gerçek yanıtıyla mükemmel şekilde senkronize olmayabilir. Verilerinizi çalışma zamanında doğrulayarak, uygulamanızda sorunlara neden olmadan önce potansiyel sorunları yakalayabilirsiniz.

Mutlu kodlamalar!