---
title: API Design Principles
category: product
entity_type: skill
price: ₺369
canonical: https://forgehouse.ai/tr/skiller/api-design-principles/
lang: tr
hreflang_alt: https://forgehouse.ai/skills/api-design-principles/
last_updated: 2026-06-20
---

# API Design Principles

> Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable…

Geliştiricilerin kullanmaktan keyif aldığı ve ekiplerin yıllarca sürdürebildiği REST ve GraphQL API'leri kurmak için bir tasarım standartları kaynağı. Her seçimi sözleşme öncelikli tasarım, idempotency, en az şaşırtma ilkesi ve katmanlı savunmaya dayandırır: kaynak modelleme, sayfalama, hata formatları, sürümleme ve N+1 problemini her iki paradigmada uygulamalı örneklerle kapsar.

## Ne için kullanılır
- Tek satır kod yazılmadan önce yeni bir REST veya GraphQL API tasarlamak
- Bir ekip için API tasarım standartları ve kuralları belirlemek
- Uygulama başlamadan önce bir API spesifikasyonunu incelemek
- API sürümleme stratejisi seçmek ve uygulamak
- Cursor tabanlı sayfalama ve tutarlı hata yanıtları tasarlamak
- DataLoader'larla GraphQL resolver'larında N+1 problemini önlemek

## Faydalar
- Entegrasyon sürtünmesini ve destek taleplerini azaltan sezgisel API'ler
- Sözleşme öncelikli spec'ler ve sürümleme disipliniyle daha az kırıcı değişiklik
- Her uç noktada tutarlı hata ve sayfalama sözleşmeleri
- Kritik işlemlerde idempotency anahtarlarıyla güvenilir mutasyonlar

## Ne içerir
- Doğru HTTP metot anlamlarıyla REST kaynak-koleksiyon tasarımı
- GraphQL şema öncelikli desenler, Relay tarzı sayfalama ve resolver tasarımı
- Avantaj-dezavantajlarıyla üç sürümleme stratejisi (URL, başlık, sorgu parametresi)
- Tutarlı hata yanıtı ve durum kodu kuralları
- HATEOAS hipermedya ve DataLoader N+1 önleme desenleri
- Aşırı veri çekme, sıkı bağlama ve eksik limitleri kapsayan yaygın hata kataloğu

## Kimler için
Diğer geliştiricilerin üzerine inşa edeceği standartları belirleyen API tasarımcıları, backend liderleri ve mimarlar.

## Nasıl çalışır
Skill, tek satır implementasyon yazılmadan önce API'yi sözleşme olarak tasarlar. Kara kutu yok, yaptığı iş tam olarak şu:
1. Önce sözleşme: OpenAPI 3.1 spec'i (veya GraphQL şeması) koddan önce yazılır. Request ve response şekilleri, status kodları ve hata formatı kilitlenir, frontend ile backend ekipleri aynı sözleşmeye karşı paralel geliştirir.
2. Kaynakları isim olarak modeller, işi HTTP fiilleri yapar: GET/POST /api/users, iç içe /users/{id}/orders. /createUser veya /getUserById gibi fiil-bazlı endpoint'ler review'da reddedilir.
3. Tekrarlayan sözleşmeleri standartlaştırır: tek sayfalama deseni (page ve page_size artı toplamlar, GraphQL'de Relay tarzı cursor), tek hata zarfı (error, message, details) ve her endpoint'te tutarlı status kodu semantiği.
4. Mutasyonlara Stripe modelini izleyerek idempotency key ekler ve versiyonlama stratejisini baştan seçer. Kırıcı değişiklik major versiyon demektir, minimum 90 gün sunset bildirimiyle.
5. GraphQL tarafında schema-first çalışır: sayfalama için tipli connection'lar, yapılandırılmış hata taşıyan mutation payload'ları ve N+1 sorgularını öldürmek için her ilişki resolver'ı DataLoader'dan geçirilir.
6. Derinlemesine savunma incelemesiyle kapatır: auth middleware, IP başına rate limiting, alan düzeyinde girdi doğrulama ve output encoding, birbirinden bağımsız fail edebilen dört ayrı katman olarak kontrol edilir.

## Sık sorulanlar
### REST ile GraphQL arasında kararsızız, bu yalnızca birine mi yardım eder?
Her iki yaklaşımı da kapsar ve her birinin dayattığı seçimleri ele alır: kaynak modelleme, sayfalama, hata biçimleri, sürümleme. Ortak ilkeler (sözleşme öncelikli tasarım, idempotensi, en az şaşırtma) hangisini seçersen seç geçerlidir.

### Bu sadece bir ekibin isimlendirme görüşü mü, yoksa savunabileceğim kararlar mı?
Her kural bir gerekçeye bağlanır: tüketici için en az şaşırtma, güvenlik için katmanlı savunma, yeniden denemeler için idempotensi. Zevk değil, bir incelemede açıklayabileceğin dengeler benimsersin.

### OpenAPI tanımımı ya da şemamı üretir mi?
Hayır, bu koddan önce kararları vermek için bir tasarım zamanı referansıdır, bir üreteç değil. İyi bir sözleşmenin neye benzediğini söyler; o sözleşmeyi yazmak ve sunmak sende kalır.

## Fiyat
₺369, tek seferlik, abonelik yok. KDV dahil.

İlgili rehber: [Yapay zekâ ile kod inceleme](https://forgehouse.ai/tr/rehberler/yapay-zeka-kod-inceleme/)