API Design Principles

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.

₺369 tek seferlik
Bir kit içine ekle →

Fiyatlara KDV (%20) dahildir. · Gerçek ajans işinden çıkarıldı · tek seferlik, kilit yok

  • Tür Skill
  • Kategori Geliştirme
  • Teslimat E-posta · anında
  • Lisans Tek seferlik
Çalışma önizlemesi
forgehouse, api-design-principles

Çalışmanın içinden · kara kutu yok

Satın almadan önce işin kendisini gö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.
Kullanım senaryoları · taktığında neler oluyor

Tek güç kaynağı. 6 hat dışarı.

api-design-principles · çekirdek

çekirdek aktif · 6 hat

  1. Tek satır kod yazılmadan önce yeni bir REST veya GraphQL API tasarlamak

    ✓ tek satır kod yazılmadan
  2. Bir ekip için API tasarım standartları ve kuralları belirlemek

    ✓ bir ekip için api tasarım
  3. Uygulama başlamadan önce bir API spesifikasyonunu incelemek

    ✓ uygulama başlamadan önce
  4. API sürümleme stratejisi seçmek ve uygulamak

    ✓ api sürümleme stratejisi
  5. Cursor tabanlı sayfalama ve tutarlı hata yanıtları tasarlamak

    ✓ cursor tabanlı sayfalama
  6. DataLoader'larla GraphQL resolver'larında N+1 problemini önlemek

    ✓ dataloader'larla graphql…
Kazanımlar · elinde kalanlar

Aldıkların sende kalır.

Zamanı ileri sar. Ne kaldığını izle.

Sonsuza dek

Sahip olmak tam olarak bu.

Kiralık yığın

yapay zekâ yazım aracı: abonelik

süresi doldu · erişim gitti

analiz paketi: abonelik

süresi doldu · erişim gitti

tasarım platformu: abonelik

süresi doldu · erişim gitti

(geriye bir şey kalmadı)

Senin ocağın

  1. Entegrasyon sürtünmesini ve destek taleplerini azaltan sezgisel API'ler

    lisans: kalıcı
  2. Sözleşme öncelikli spec'ler ve sürümleme disipliniyle daha az kırıcı değişiklik

    lisans: kalıcı
  3. Her uç noktada tutarlı hata ve sayfalama sözleşmeleri

    lisans: kalıcı
  4. Kritik işlemlerde idempotency anahtarlarıyla güvenilir mutasyonlar

    lisans: kalıcı

abonelikler biter · tapular bitmez

Ne içerir · eksiksiz manifest

Kutudaki her şey.

Bir parçayı eline al. Çalışırken izle.

Doğru HTTP metot anlamlarıyla REST kaynak-koleksiyon tasarımı

parça 01 / 06 · kutuda

6 parça · tek çalışan sistem · e-postayla anında teslim

Kimler için

Bu herkes için dövülmedi.

  • Araç kiralamayı sahip olmaya tercih ediyorsan, sana göre değil.
  • Yığınını senin yerine başkası yönetsin istiyorsan, sana göre değil.
  • Tahmin etmekten memnunsan, sana göre değil.
Hâlâ burada mısın? Güzel.

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

o zaman bu senin için dövüldü.

Hangi AI ile çalışır

Tasarımı gereği evrensel: her yapay zekada çalışır. Açık Agent Skills + MCP biçiminde gelir (Claude’da yerleşik); ChatGPT, Gemini, Cursor ve Copilot aynı dosyaları kendine uyarlar.

  • Claude Yerleşik biçim
  • ChatGPT Açık standartla uyarlanır
  • Gemini Açık standartla uyarlanır
  • Cursor Açık standartla uyarlanır
  • Copilot Açık standartla uyarlanır
Sorular · hâlâ havada

Aklındakini yakala.

hava temizlendi. seninle ocak arasında hiçbir şey kalmadı.
bir kıvılcım yakala: ocak cevaplar

  1. 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.

  2. 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.

  3. 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.

  4. Nasıl teslim edilir?

    Satın alımdan hemen sonra e-posta ile iletilir, kuruluma hazır, anında indirilir; bekleme yok.

  5. Tek seferlik mi, abonelik mi?

    Tek seferlik alımdır; abonelik veya gizli ücret yoktur. Fiyata KDV (%20) dahildir.

  6. İade alabilir miyim?

    Dijital ürün olduğu için indirildikten sonra iade yapılmaz. Bu yüzden ne içerdiğini ve kime uygun olduğunu burada açıkça paylaşıyoruz.