REST API Nasıl Oluşturulur: Tasarım, Güvenlik ve Yayınlama

REST API oluşturmak için uygulamanızın yönettiği kaynakları (kullanıcılar, siparişler, rezervasyonlar) listeleyin, her birine /orders ve /orders/{id} gibi bir URL verin ve eylemler için HTTP metotlarını kullanın: okumak için GET, oluşturmak için POST, güncellemek için PATCH, silmek için DELETE. Anlamlı durum kodları ile JSON döndürün, her girdiyi doğrulayın, sunucuda kimlik doğrulama ve kayıt bazında yetki kontrolü isteyin ve listeleri sayfalara bölün. Ardından uç noktaları belgeleyin ve API'yi HTTPS arkasında yayınlayın.

Bu rehber tasarım kararlarını, örnek bir rota setini, bir yapay zeka uygulama oluşturucusu için istemleri ve güvenlik açıklarına yol açan hataları kapsar. API'ler sizin için yeniyse, API nedir sayfasıyla başlayın.

Ne zaman REST API'ye ihtiyacınız olur

• Web arayüzünüzün verileri sunucuya kaydetmesi ve sunucudan yüklemesi gerekiyorsa
• Bir mobil uygulamanın, iş ortağının veya otomasyon aracının verilerinize erişmesi gerekiyorsa
• Diğer servislerin size olaylar göndermesi gerekiyorsa (webhook'lar)
• Çalışmayı bir ön yüz ve bir arka yüz ekibi arasında bölüyorsanız

REST en yaygın stildir, ancak tek seçenek değildir. REST ile GraphQL sayfası, tek ve esnek bir sorgu uç noktasının ne zaman daha uygun olduğunu açıklar.

Önce tasarlayın: kaynaklar ve rotalar

Uygulamanızdaki isimleri ve insanların bunlarla ne yaptığını yazın. Basit bir rezervasyon uygulaması için:

Bunlar oluşturma, okuma, güncelleme ve silme işlemlerine karşılık gelir; bkz. CRUD nedir. Uyulmaya değer kurallar:

• URL'lerde çoğul isimler, fiil yok: /getBookings yerine /bookings.
• Sahipliği netleştirdiğinde yalnızca bir seviye iç içe kullanın: /bookings/{id}/notes.
• CRUD dışındaki eylemler alt kaynak olabilir: sihirli bir PATCH yerine POST /bookings/{id}/cancel daha açıktır.
• Alanlar için tutarlı adlandırma kullanın, örneğin her yerde created_at.

Durum kodları ve hatalar

İstemcilerin metni ayrıştırmadan ne olduğunu anlayabilmesi için standart HTTP kodlarını kullanın:

Hataları tek ve tutarlı bir JSON biçiminde döndürün, örneğin {"error": {"code": "slot_taken", "message": "Bu saat artık müsait değil."}}, ve yanıtlarda asla yığın izleri (stack trace) ya da veritabanı hatalarını göstermeyin.

Seçenekler ve ödünler

Adım adım

1. Yukarıdaki gibi kaynakları ve rotaları listeleyin, her birini kimin çağırabileceğiyle birlikte.
2. İhtiyacınız olan alanlar ve ilişkilerle veriyi veritabanınızda modelleyin.
3. Önce okuma rotalarını, ardından oluşturma, güncelleme ve silme rotalarını yapın.
4. Her yazma işleminde bir şema kütüphanesiyle girdiyi doğrulayın: zorunlu alanlar, türler, uzunluklar, izin verilen değerler. Bilinmeyen alanları reddedin.
5. Kimlik doğrulama ekleyin, ardından kayıt bazında yetkilendirme ekleyin: /bookings/42 isteği yalnızca birinin giriş yapmış olmasını değil, 42 numaralı rezervasyonun çağırana ait olduğunu kontrol etmelidir.
6. Her listeyi sayfalara bölün ve sayfa boyutunu sınırlayın.
7. Giriş ve pahalı rotalara hız sınırı koyun. Bkz. hız sınırlama.
8. CORS'u yalnızca başka alan adlarındaki tarayıcıların API'yi çağırması gerekiyorsa yapılandırın ve bu kökenleri açıkça listeleyin. CORS hatalarını düzeltme sayfası karşılaşacağınız hataları anlatır.
9. Her rota için, başarısız senaryolar dahil dokümantasyon ve testler yazın.
10. Yayınlayın: gizli bilgiler ortam değişkenlerinde, HTTPS, günlükler ve bir sağlık kontrolüyle.

Yapay zeka oluşturucunuza verilecek istemler

İskelet:

Şu rotalara sahip rezervasyonlar için bir REST API oluştur: GET /api/health, GET /api/bookings (sayfalı, sayfa başına en fazla 50), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Verileri veritabanımızda sakla. İstek gövdelerini bir şema kütüphanesiyle doğrula ve bilinmeyen alanları reddet. JSON hatalarını doğru durum kodlarıyla (400, 401, 403, 404, 409) {"error": {"code", "message"}} biçiminde döndür. Gizli bilgileri ortam değişkenlerinde tut.

Güvenlik:

Her rezervasyon rotası için giriş iste. Her okuma, güncelleme ve silme işleminde, rezervasyonun geçerli kullanıcıya ait olduğunu sunucuda kontrol et; değilse 404 döndür. İstek gövdesinden asla kullanıcı kimliği veya rol kabul etme. POST /api/bookings rotasını kullanıcı başına dakikada 20 ile sınırla. Hataları sunucuda günlüğe yaz, yığın izlerini döndürme.

Dokümantasyon:

Bu rotaların bir OpenAPI açıklamasını ve her biri için örnek istek ve yanıtlar içeren kısa bir README yaz.

API'nizi test etmek

Testleri ön yüzün dışından yapın, çünkü saldırganlar da öyle yapacaktır:

• Her rota geçerli girdiyle çalışır ve belgelenen biçimi ve kodu döndürür
• Eksik veya geçersiz alanlar açık bir mesajla 400 döndürür
• Token olmadan her korumalı rota 401 döndürür
• A kullanıcısı, ID ile B kullanıcısının kaydını istediğinde 404 veya 403 alır
• Listeler sayfalıdır; çok büyük bir limit sınırlandırılır
• Tekrarlanan veya çakışan oluşturma işlemleri 500 değil 409 döndürür
• Hız sınırları 429 döndürür
• Hata yanıtlarında yığın izi, SQL veya gizli bilgi yok
• CORS yalnızca amaçladığınız kökenlere izin veriyor

Sık yapılan hatalar

• Oturumu kontrol edip sahipliği kontrol etmemek. En yaygın API açığı: oturum açmış herhangi bir kullanıcı ID'yi değiştirerek herhangi bir kayda erişebilir.
• İstemciye güvenmek. İstek gövdesindeki fiyatlar, roller ve kullanıcı kimlikleri değiştirilebilir.
• Veritabanı satırlarının tamamını döndürmek. Parola özetleri ve dahili alanlar sızar. Her yanıtta neyin yer alacağını seçin.
• Sınırsız listeler. Her kaydı isteyen tek bir istek tüm uygulamayı yavaşlatabilir.
• İçinde hata mesajı olan 200 OK. İstemciler ve izleme sistemleri başarısız olduğunu anlayamaz.
• CORS'un çerez kullanan bir API'de her şeye izin verecek şekilde ayarlanması.
• Sağlık kontrolü veya günlük olmaması, bu yüzden kesintileri kullanıcılardan öğrenmek.

Daha geniş bir yayın öncesi kontrol için bkz. yapay zeka ile oluşturulan uygulamalar için güvenlik kontrol listesi.

Mythex'te REST API oluşturmak

Mythex'ten API'yi uygulamanızın bir parçası olarak veya kendi başına bir servis olarak isteyebilirsiniz. Dokümantasyondaki REST API backend tarifinde bir başlangıç istemi var: çerçevenizi ve rotalarınızı belirtin, açık JSON hataları isteyin, gizli bilgileri ortam değişkenlerinde tutun ve bir Dockerfile ekleyin. Node, Python, C#, Java ve diğer dillerdeki konteyner tabanlı backend'ler bir Dockerfile ile yayınlanır ve Mythex dağıtımı Publish bölümünden yönetir (API backend'leri). Bir proje web sitesini ve bir API sunucusunu yan yana çalıştırabilir ve önizlemede aralarında geçiş yapabilirsiniz. API'nin bir veritabanına ihtiyacı varsa bunu sohbette isteyin. API'nizin etrafındaki zamanlanmış işler için bkz. arka plan işleri nasıl çalıştırılır.

Sorular