REST API Uç Noktası Tasarımı ve OpenAPI Taslağı

Prompt

Sen tutarlı, geliştirici dostu ve sürdürülebilir API'ler tasarlayan bir backend mimarısın. Proje ve API'yi kim kullanacak: [PROJE] Kaynaklar (varlıklar) ve aralarındaki ilişkiler: [KAYNAKLAR] İş kuralları ve yetkiler (kim neyi yapabilir): [KURALLAR] Teknoloji ve kimlik doğrulama yöntemi: [TEKNOLOJI] Başlamadan önce: Tasarımı etkileyecek belirsiz bir iş kuralı varsa en fazla 3 kısa soru sor ve yanıtımı bekle. Tasarım: 1. Uç nokta tablosu: Metot | Yol | Açıklama | Yetki | Başarılı durum kodu. Çoğul isimler, iç içe kaynaklarda en fazla iki seviye. 2. Her kaynak için örnek istek ve yanıt JSON'u (alan adları tutarlı biçimde, tarih ISO 8601). 3. Ortak kurallar: - Sayfalama (cursor mı offset mi, neden), filtreleme ve sıralama parametreleri. - Tek tip hata yanıtı biçimi ve kullanılacak durum kodları (400, 401, 403, 404, 409, 422, 429). - Sürümleme stratejisi. - İdempotency: Hangi işlemlerde ve nasıl. 4. Güvenlik: Yetkilendirme kontrolleri, hız sınırı, hassas alanların yanıtta gizlenmesi. 5. OpenAPI 3.1 taslağı: En az bir kaynağın tüm uç noktalarını içeren YAML. Kurallar: Fiil içeren yollar ("/getOrders") kullanma; eylem gerektiren istisnai durumları gerekçelendir.

Doldurulacak alanlar 4

[PROJE]: Proje ve API kullanıcıları Örn. Spor salonu üyelik ve ders rezervasyon sistemi; mobil uygulama ve yönetim paneli kullanacak
[KAYNAKLAR]: Kaynaklar ve ilişkileri Örn. Üye, Eğitmen, Ders (eğitmene bağlı), Rezervasyon (üye + ders), Üyelik paketi
[KURALLAR]: İş kuralları ve yetkiler Örn. Üye kendi rezervasyonunu ders saatinden 2 saat öncesine kadar iptal edebilir; ders kontenjanı dolunca bekleme listesi
[TEKNOLOJI]: Teknoloji ve kimlik doğrulama Örn. Node.js + NestJS, JWT

Örnek çıktı

1. Uç noktalar
| Metot | Yol | Açıklama | Yetki | Kod |
| GET | /v1/classes | Dersleri listele (tarih, eğitmen filtresi) | Herkes | 200 |
| POST | /v1/classes/{classId}/reservations | Derse rezervasyon yap | Üye | 201 |
| DELETE | /v1/reservations/{id} | Rezervasyonu iptal et | Rezervasyon sahibi | 204 |
...

3. Hata biçimi
{
"error": {
"code": "CANCELLATION_WINDOW_CLOSED",
"message": "Ders başlangıcına 2 saatten az kaldığı için iptal edilemez.",
"details": { "classStartsAt": "2026-10-03T18:00:00Z" }
}
}
İptal süresi geçmişse 409, kontenjan doluysa 409 + "WAITLISTED" durumu ile 202.

5. OpenAPI (kısaltılmış)
openapi: 3.1.0
paths:
/v1/classes/{classId}/reservations:
post:
summary: Derse rezervasyon yap
...

ChatGPT'de Aç Yerel modelimde dene