API Tasarımında Schema-First Dönemi: Microsoft TypeSpec ile OpenAPI ve SDK Üretimi

0:00

/0

1×

API Tasarımında Schema-First Dönemi: Microsoft TypeSpec ile OpenAPI ve SDK Üretimi

Modern yazılım mimarilerinde API'ler, sistemlerin birbiriyle haberleşmesini sağlayan en kritik köprülerdir. Ancak genişleyen mikroservis ağları ve büyüyen ekiplerle birlikte API tasarlamak, dokümante etmek ve bu API'ler için istemci (client) kütüphaneleri (SDK) üretmek karmaşık bir süreç haline gelebilir.

Yıllardır süregelen "Code-First" (Önce Kod) ve "Schema-First" (Önce Şema) tartışmasında, modern yazılım dünyası net bir şekilde Schema-First yaklaşımına kaymış durumda. Fakat el ile binlerce satırlık JSON veya YAML formatında OpenAPI (Swagger) dosyaları yazmak geliştiriciler için tam bir çileye dönüşebiliyor.

İşte tam bu noktada sahneye Microsoft tarafından geliştirilen açık kaynaklı TypeSpec çıkıyor. TypeScript benzeri esnek ve modern sözdizimiyle TypeSpec, Schema-First yaklaşımını yepyeni bir seviyeye taşıyor. Bu yazıda, TypeSpec'in ne olduğunu, OpenAPI süreçlerini nasıl kolaylaştırdığını ve tek bir kaynaktan çoklu dilde SDK üretimini nasıl sağladığını inceleyeceğiz.

Schema-First Yaklaşımı Nedir ve Neden Zor?

Schema-First yaklaşımı, kod yazmaya başlamadan önce API kontratının (contract) tanımlanmasını savunur. Bu yaklaşım; * Backend ve Frontend ekiplerinin paralel çalışmasını sağlar, * API tasarım hatalarının erken aşamada fark edilmesini kolaylaştırır, * Otomatik dokümantasyon ve test süreçlerine zemin hazırlar.

Ancak klasik OpenAPI (Swagger) YAML/JSON dosyaları ile Schema-First uygulamak bazı zorlukları beraberinde getirir:

1. Kopyala-Yapıştır Karmaşası (DRY Prensibinin İhlali): YAML dosyalarında kod tekrarı yapmak çok kolaydır. Modülerlik sınırlıdır.
2. Okunabilirlik Sorunları: Yanlış yapılan tek bir girinti (indentation) tüm YAML dosyasını bozabilir. Binlerce satırlık OpenAPI dosyalarını okumak ve yönetmek oldukça zordur.
3. Soyutlama Eksikliği: Karmaşık veri tiplerini veya genel API kalıplarını (pagination, error handling vb.) tekrar tekrar tanımlamanız gerekir.

Karşınızda Microsoft TypeSpec: API Tasarımı İçin "TypeScript" Dokunuşu

TypeSpec (eski adıyla Cadl), Microsoft tarafından API tasarlamayı pratik, modüler ve tip güvenli hale getirmek amacıyla geliştirilmiş bir alan özgü dildir (DSL - Domain Specific Language).

Geliştiricilerin zaten çok iyi bildiği TypeScript sözdiziminden esinlenen TypeSpec, bir "API derleyicisi" gibi çalışır. Yazdığınız sade TypeSpec kodunu alır ve standart OpenAPI v3, JSON Schema veya doğrudan uygulamanız için Client SDK'ları gibi çıktılara dönüştürür.

TypeSpec’in Öne Çıkan Özellikleri

• Aşina Olunan Sözdizimi: TypeScript veya C# bilen her geliştirici, dakikalar içinde TypeSpec yazmaya başlayabilir.
• Yüksek Modülerlik ve Yeniden Kullanılabilirlik: Veri tiplerini, parametreleri ve yanıtları bileşenlere ayırabilir, projeler arasında paket olarak paylaşabilirsiniz.
• Güçlü IDE Desteği: VS Code ve Visual Studio için sunulan resmi eklentiler sayesinde anında hata denetimi (linting), otomatik tamamlama (autocomplete) ve biçimlendirme desteği sunar.
• Ekosistem Bağımsızlığı: TypeSpec sadece REST veya OpenAPI için değildir. Doğru eklentilerle GraphQL veya gRPC gibi farklı protokoller için de kaynak kod oluşturabilir.

Pratik Örnek: TypeSpec Sözdizimi Nasıl Görünür?

Geleneksel bir OpenAPI YAML dosyası ile TypeSpec kodunu kıyasladığımızda aradaki farkı net bir şekilde görebiliriz.

Aşağıdaki TypeSpec kodu, basit bir "Kullanıcı (User)" API'sini tanımlamaktadır:

import "@typespec/http";
import "@typespec/rest";

using TypeSpec.Http;
using TypeSpec.Rest;

@service({
  title: "Kullanıcı Yönetim Servisi",
})
namespace UserService;

model User {
  id: string;
  name: string;
  email: string;
  role: "admin" | "user";
}

@route("/users")
interface Users {
  @get list(): User[];

  @get read(@path id: string): User | ErrorResponse;

  @post create(@body user: OmitProperties<User, "id">): User;
}

model ErrorResponse {
  code: string;
  message: string;
}

Bu Kod Neden Mükemmel?

1. Sadelik: Onlarca satır YAML yerine sadece birkaç satırlık okunabilir ve şık bir kod.
2. Esneklik: OmitProperties<User, "id"> gibi yardımcı tipler sayesinde, yeni bir kullanıcı oluştururken id alanının gönderilmemesi gerektiğini tek satırda belirtebildik.
3. Tip Güvenliği: role: "admin" | "user" tanımlamasıyla enum yapısını doğrudan dile entegre ettik.

Bu TypeSpec dosyası derlendiğinde (tsp compile .), arka planda yüzlerce satırlık kusursuz bir OpenAPI 3.0 JSON/YAML dosyası otomatik olarak üretilir.

Tek Kaynaktan Tüm Ekosisteme: OpenAPI ve SDK Üretimi

TypeSpec’in sunduğu en büyük güç, "Single Source of Truth" (Tek Doğruluk Kaynağı) felsefesidir. API'nizi TypeSpec ile bir kez tanımlarsınız ve mimarinizin ihtiyaç duyduğu tüm çıktıları derleme adımında elde edersiniz.

                  ┌───> OpenAPI 3.0 Spec (Swagger UI / Redoc)
                  │
[ TypeSpec Code ] ┼───> C# Client SDK
                  │
                  ├───> TypeScript / JS Client SDK
                  │
                  └───> Python / Java SDK

1. Dokümantasyon ve OpenAPI Üretimi

Derleyiciye eklenen @typespec/openapi3 eklentisi sayesinde Swagger UI veya Redoc ile tam uyumlu OpenAPI spesifikasyonu elde edilir. API dokümantasyonunuz her zaman güncel kalır.

2. Çoklu Dilde İstemci SDK Üretimi

Microsoft, TypeSpec ekosistemi için resmi SDK üreteçleri (emitters) sunmaktadır. TypeSpec tanımınızdan doğrudan: * TypeScript / JavaScript * C# (.NET) * Python * Java

dillerinde tip güvenli istemci kütüphaneleri oluşturabilirsiniz. Böylece API'nizi tüketen frontend veya mobil ekipler, endpoint'lere istek atarken otomatik tamamlama ve tip güvenliği konforunu yaşarlar.

TypeSpec ile Geliştirme Sürecine Nasıl Başlanır?

TypeSpec projelerine başlamak son derece hızlı ve basittir. Node.js ortamınızın olması yeterlidir.

1. Kurulum

TypeSpec CLI aracını global olarak yükleyin:

npm install -g @typespec/compiler

2. Yeni Bir Proje Başlatma

Boş bir klasörde aşağıdaki komutu çalıştırarak yönlendirmeli kurulumu başlatabilirsiniz:

tsp init

Bu komut size proje tipini (REST API, OpenAPI vb.) soracak ve gerekli bağımlılıkları içeren bir main.tsp dosyası ile package.json oluşturacaktır.

3. Derleme

TypeSpec kodlarınızı OpenAPI çıktısına dönüştürmek için:

tsp compile .

Komut çalıştıktan sonra tsp-output klasörü altında derlenmiş OpenAPI JSON/YAML dosyalarınızı görebilirsiniz.

Son Söz: API Tasarımında Yeni Standart

Yazılım dünyasında karmaşıklığı azaltan ve geliştirici deneyimini (Developer Experience - DX) ön plana çıkaran araçlar her zaman kazanır. Microsoft TypeSpec, el ile OpenAPI yazma çilesini sona erdirirken, Schema-First yaklaşımının tüm avantajlarını geliştiricilere zahmetsizce sunuyor.

Eğer projelerinizde mikroservis mimarisi kullanıyorsanız, birden fazla dilde SDK ihtiyacınız varsa veya OpenAPI dosyalarınızı yönetmekte zorlanıyorsanız, TypeSpec’e bir şans vermenin tam zamanı.

Siz de API süreçlerinizde Schema-First yaklaşımını kullanıyor musunuz? TypeSpec hakkındaki düşüncelerinizi yorumlarda paylaşmayı unutmayın!