İstemcilerin Güvenebileceği API'ler Nasıl Tasarlanır? Sözleşmeden Başlayan Pratik Rehber

Bir API başka bir takıma verilen sözdür. Mobil uygulama, iş ortağı entegrasyonu veya gelecekteki kendi arayüzünüz onun davranışına dayanabilir. Bu noktadan sonra alan adını değiştirmek yalnızca yerel bir refaktör değildir. Bu yüzden controller yazmadan önce istemcinin amacını, hata durumlarını ve güvenli tekrar davranışını belirlerim.

Örnek olarak bir kurs kayıt API'si tasarlayalım. Öğrenci kursu görür, kayıt ister ve kalıcı bir kayıt kimliği ile durum alır. Kurs dolabilir; istek iki kez gelebilir; sunucu kaydı yaptıktan sonra ağ yanıtı kaybolabilir. Tasarımın kalitesi tam da bu durumlarda ortaya çıkar.

1. İstemci öyküsünü ve kuralları yazın

Akışı açıkça belirtin: Kimliği doğrulanmış öğrenci kursu görüntüler, kayıt isteği gönderir, durumu alır ve zaman aşımından sonra çift kayıt oluşturmadan yeniden deneyebilir. Sunucu kuralları: öğrenci ve kurs için tek aktif kayıt, kayıt dönemi açıkken işlem, kapasitenin aşılmaması. Ödeme varsa koltuğun ne zaman ayrıldığını ve başarısız ödemede ne zaman serbest bırakıldığını ürün ekibiyle kararlaştırın.

Koddan önce örnek istek ve yanıtı frontend geliştiricisine gösterin. Eksik alan veya belirsiz bir durum, henüz değiştirmesi ucuzken bulunur.

2. Kaynakları iş akışına göre adlandırın

İstek	Amaç	Başarılı yanıt
GET /v1/courses/{courseId}	Kursu oku	200 OK
GET /v1/courses?cursor=...&limit=20	Kursları listele	200 OK
POST /v1/courses/{courseId}/enrollments	Kayıt iste	201 Created
GET /v1/enrollments/{enrollmentId}	Kayıt durumunu oku	200 OK
DELETE /v1/enrollments/{enrollmentId}	İzin verilen iptal	204 No Content

İşlem asenkron tamamlanıyorsa durum kaynağıyla 202 Accepted daha doğru olabilir. Gerçekte tamamlanan işe uygun kodu seçin. GET okuma içindir; POST oluşturma veya süreç başlatma içindir. Bazı HTTP yöntemlerinin idempotent olması, her POST isteğinin güvenle yinelenebileceği anlamına gelmez. URL'de controller ve tablo adlarını açığa çıkarmayın.

3. İstek ve yanıtı birlikte tasarlayın

POST /v1/courses/crs_42/enrollments HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: 9bfa06f8-3eb5-4d5d-85cd-43b02b56bf11

{"source":"course_page"}

Öğrenci kimliğini doğrulanmış oturumdan alın; istemcinin değiştirebileceği learnerId alanına güvenmeyin. Örnek yanıt:

HTTP/1.1 201 Created
Location: /v1/enrollments/enr_7f3
Content-Type: application/json

{"id":"enr_7f3","courseId":"crs_42","status":"confirmed","createdAt":"2026-09-29T10:30:00Z"}

Kimliğin opak olup olmadığını, durum geçişlerini ve boş olabilen alanları belgeleyin. Veritabanı satırını olduğu gibi döndürmeyin; iç notları ve başka öğrencilerin verilerini dışarı açmayın. Listelerde data ve page.nextCursor gibi tutarlı bir yapı kullanın. Sıralama ve filtreleri tanımlayın; kararlı sıralama olmadan cursor sayfalaması kayıt atlayabilir veya tekrar gösterebilir.

4. Hataları kullanılabilir hale getirin

“Bir hata oluştu” istemciye çözüm sunmaz. Kapalı kayıt dönemini, geçersiz oturumu, yetki eksikliğini ve sunucu arızasını ayırın. RFC 9457 Problem Details ortak bir gövde tanımlar:

{
  "type": "https://api.example.com/problems/enrollment-closed",
  "title": "Enrollment is closed",
  "status": 409,
  "detail": "This course stopped accepting enrollments."
}

Üretimde type gerçek bir problem tanımına götürmelidir. Alan doğrulama hatalarını da belgeleyin. SQL mesajlarını, stack trace'leri ve sırları yanıta koymayın; güvenli sunucu günlükleri ve ilişkilendirme kimliği kullanın. 401 kimlik doğrulama, 403 yetki, 404 bulunamayan kaynak, 409 durum çatışması ve 429 hız sınırı için açık bir politika belirleyin.

5. Tekrar ve eşzamanlılığı tasarlayın

Sunucu kaydı oluşturup yanıt kaybolursa istemci sonucu bilemez. Idempotency-Key ile denemeye özel anahtar gönderir; sunucu aynı anahtar ve aynı istek için önceki sonucu saklar ve tekrar döndürür. Farklı istekle aynı anahtarı reddedin; kapsamı ve saklama süresini belirtin. Bu, POST için kendiliğinden gelen HTTP garantisi değil, sizin tasarladığınız davranıştır.

Veritabanı kısıtlarıyla çift aktif kayıtları da engelleyin. Son koltuğa aynı anda gelen iki istek için işlem veya güvenli rezervasyon mekanizması kullanın. Ardışık testler yetmez; eşzamanlı test yapın. Webhook ve arka plan işlerinin de yinelenebileceğini varsayın.

6. Kimlik doğrulama ve yetkilendirmeyi ayırın

Kimlik doğrulama “kim çağırıyor?”, yetkilendirme “bu kaynağa erişebilir mi?” sorusudur. Geçerli bir token, başka öğrencinin kaydını okuma izni vermez. Öğrenci, eğitmen ve yönetici kurallarını sunucuda uygulayın. İstek gövdesindeki rol bilgisini güvenilir saymayın. Token'ları loglamayın; 429 için geri çekilme davranışını ve sınırın kullanıcıya mı tenant'a mı uygulandığını belirtin.

7. OpenAPI, testler ve değişim planı

Yolları, şemaları, güvenliği, yanıtları ve hata örneklerini OpenAPI ile anlatın. Bir istemci geliştiricisinden yalnızca belgeye bakarak entegrasyon yapmasını isteyin. Soruları sözleşmedeki eksikleri gösterir. Testlerde 201, aynı anahtar ve gövdeyle tekrar, farklı gövdeyle ret, dolu kurs, başkasının kaydına erişim yasağı, son koltuk yarışı ve sayfalama sırası olsun.

/v1 yazmak tek başına sürüm stratejisi değildir. Değişiklik günlüğü tutun, kullanımdan kaldırmayı duyurun, eski istemcileri ölçün ve geçiş örneği verin. Alanın anlamını sessizce değiştirmeyin. pending_payment gibi yeni durumlara karşı eski istemcilerin ne yapacağını da düşünün.

Yayından önce kısa kontrol

İstemci başarılı ve başarısız sonuçları açıklayabiliyor mu? Kaynak yetkisi sunucuda mı? Tekrar veya yarış olduğunda ne olur? Sayfalama ve sıralama belirli mi? OpenAPI çalışan davranışla uyuşuyor mu? Hatalar hassas veri sızdırmadan izlenebiliyor mu? Değişiklik planı var mı?

Bir API, mutlu yol bir kez çalıştığı için güvenilir olmaz. Ağ kesintisinden sonra toparlanabildiğinde, dolu kursu açıklayabildiğinde ve sonraki sürümünüzden sağ çıkabildiğinde güven kazanır.

Kaynaklar

• HTTP Semantics, RFC 9110
• Problem Details, RFC 9457
• OpenAPI Specification