- Konu sahibi
- #1
Web API yazmak için önce istemci ile sunucu arasındaki sözleşmeyi tasarlayın; ardından HTTP isteklerini karşılayan uç noktaları, doğrulama kurallarını, yetki kontrollerini ve tutarlı yanıtları uygulayın. Basit bir API için kaynakları belirleyip HTTP metotlarını bu kaynakların işlemlerine eşleyebilir, JSON kullanabilir ve her isteğin sonucunu uygun HTTP durum koduyla bildirebilirsiniz.
İstemci; tarayıcı, mobil uygulama veya başka bir sunucu olabilir. İstemci bir HTTP isteği gönderir. İstek; metot, hedef adres, başlıklar ve gerekiyorsa gövde içerir. Sunucu isteği alır, kimlik ve yetki kontrollerini yapar, veriyi doğrular, iş mantığını çalıştırır ve bir HTTP yanıtı döndürür. Yanıtta durum kodu, başlıklar ve çoğu JSON tabanlı API'de veri veya hata açıklaması bulunur.
HTTP metodu yalnızca URL'deki eylem adını tekrar etmemelidir. Örneğin
Durum kodu istemcinin yalnızca metin mesajına güvenmeden karar vermesini sağlar. Geçersiz veya bozuk istek yapısı için
Node.js kurulu bir bilgisayarda aşağıdaki kodu
Terminalde
Bu öğrenme örneği yalnızca yerel arayüzü dinler; kimlik doğrulama, kalıcı veritabanı veya yazma işlemi içermez. İnternete açılacak üretim servisine dönüşmesi için aşağıdaki kontroller ayrıca uygulanmalıdır. Yeni kayıt oluşturmayı eklediğinizde gövdeyi doğrulayın; kayıt gerçekten oluşturulduktan sonra
Örneğin görev uygulamasında
İlk sürümde az sayıda ve net uç nokta oluşturun. Listeleme uç noktalarında sayfalama, filtreleme ve sıralama sınırlarını baştan tanımlayın; istemcinin sınırsız veri çekmesine izin vermeyin. Yanıt sözleşmesini değiştirirken mevcut istemcileri bozmayacak şekilde yeni alanları geriye dönük uyumlu ekleyin. Kırıcı değişiklik gerekiyorsa sürümleme ve kaldırma takvimini belgelendirin.
Yaygın hatalar her durumda
Bir diğer hata da dış servisten gelen veriyi otomatik olarak güvenilir kabul etmektir. Harici API yanıtlarını da şema, boyut, zaman aşımı ve hata davranışı açısından kontrol edin. API dokümantasyonunu gerçek davranışla eşleştirin; dokümanda bulunan fakat sunucuda çalışmayan bir uç nokta istemci tarafında doğrudan entegrasyon sorununa dönüşür.
İlk uç nokta kodlanmadan önce temel sözleşme hazırlanmalıdır. URL, metot, istek alanları, yanıt örnekleri, durum kodları ve yetki gereksinimleri önceden yazılırsa istemci ve sunucu ekipleri farklı varsayımlarla ilerlemez.
Hayır. Kimlik doğrulama yöntemi uygulamanın istemci türüne, tehdit modeline ve mevcut kimlik altyapısına göre seçilir. JWT yalnızca bir seçenektir; kullanılacak yöntemin saklama, yenileme, iptal ve yetki kapsamı kuralları ayrıca tasarlanmalıdır.
Web API nasıl çalışır?
İstemci; tarayıcı, mobil uygulama veya başka bir sunucu olabilir. İstemci bir HTTP isteği gönderir. İstek; metot, hedef adres, başlıklar ve gerekiyorsa gövde içerir. Sunucu isteği alır, kimlik ve yetki kontrollerini yapar, veriyi doğrular, iş mantığını çalıştırır ve bir HTTP yanıtı döndürür. Yanıtta durum kodu, başlıklar ve çoğu JSON tabanlı API'de veri veya hata açıklaması bulunur.
HTTP metodu yalnızca URL'deki eylem adını tekrar etmemelidir. Örneğin
GET veri okumak, POST yeni bir işlem veya kayıt oluşturmak, PUT bir kaynağın mevcut durumunu bütünüyle değiştirmek, PATCH kısmi değişiklik uygulamak ve DELETE kaynağı kaldırmak için kullanılabilir. GET ile veri değiştirmek doğru değildir; önbellekleme, tekrar çalıştırma ve güvenlik kontrolleri açısından beklenmeyen sonuçlar doğurabilir.Durum kodu istemcinin yalnızca metin mesajına güvenmeden karar vermesini sağlar. Geçersiz veya bozuk istek yapısı için
400 Bad Request, gerekli kimlik bilgilerinin eksik veya geçersiz olduğu istek için 401 Unauthorized, sunucunun isteği anlayıp yerine getirmeyi reddettiği işlem için 403 Forbidden, bulunamayan kaynak için 404 Not Found kullanılabilir. 403 tek başına kullanıcının kimliğinin doğrulandığını kanıtlamaz. İstek söz dizimsel olarak doğru olduğu hâlde gönderilen alanlar iş kuralını karşılamıyorsa 422 Unprocessable Content uygun olabilir. Beklenmeyen sunucu sorunları 5xx sınıfında olmalıdır.Yerelde çalışan küçük API örneği
Node.js kurulu bir bilgisayarda aşağıdaki kodu
server.cjs olarak kaydedin. Örnek, ek paket gerektirmeden yalnızca görev listeleme uç noktasını uygular:
Kod:
const http = require('node:http');
const tasks = [{ id: 42, title: 'Yedeklemeyi kontrol et', completed: false }];
http.createServer((req, res) => {
const send = (status, data, headers = {}) => {
res.writeHead(status, {
'Content-Type': 'application/json; charset=utf-8', ...headers
});
res.end(JSON.stringify(data));
};
const pathname = (req.url || '').split('?')[0];
if (pathname !== '/api/tasks') {
return send(404, { error: 'not_found' });
}
if (req.method !== 'GET') {
return send(405, { error: 'method_not_allowed' }, { Allow: 'GET' });
}
send(200, tasks);
}).listen(3000, '127.0.0.1');Terminalde
node server.cjs çalıştırın; başka bir terminalde curl -i http://127.0.0.1:3000/api/tasks ile yanıtı inceleyin. Beklenen sonuç 200 ve bir JSON dizisidir. Bilinmeyen yol 404, desteklenmeyen metot 405 döndürür.Bu öğrenme örneği yalnızca yerel arayüzü dinler; kimlik doğrulama, kalıcı veritabanı veya yazma işlemi içermez. İnternete açılacak üretim servisine dönüşmesi için aşağıdaki kontroller ayrıca uygulanmalıdır. Yeni kayıt oluşturmayı eklediğinizde gövdeyi doğrulayın; kayıt gerçekten oluşturulduktan sonra
201 Created ve oluşturulan kaydı gösteren bir yanıt kullanın.Örneğin görev uygulamasında
tasks kaynağı şöyle tasarlanabilir:| İşlem | Metot | Uç nokta | Tipik yanıt |
|---|---|---|---|
| Listeleme | GET | /api/tasks | 200 OK |
| Oluşturma | POST | /api/tasks | 201 Created |
| Kısmi güncelleme | PATCH | /api/tasks/42 | 200 OK veya 204 No Content |
| Silme | DELETE | /api/tasks/42 | 204 No Content |
Uygulama adımları
- Kullanıcı senaryolarını ve kaynakları yazın. Örneğin görev listeleme, tek görev görüntüleme, oluşturma, güncelleme ve silme işlemlerini ayırın.
- Uç noktaları ve metotları tanımlayın.
/api/createTaskyerine kaynak odaklıPOST /api/taskskullanın. - İstek ve yanıt sözleşmesini belirleyin. Zorunlu alanları, veri tiplerini, uzunluk sınırlarını, hata biçimini, sayfalama ve filtreleme kurallarını belgeleyin.
- Yönlendirme, doğrulama, iş mantığı, veri erişimi ve hata yönetimini ayrı katmanlar hâlinde düzenleyin.
- Gelen tüm veriyi sunucuda doğrulayın. İstemci tarafındaki JavaScript kontrolleri kullanıcı deneyimine yardımcı olur; güvenlik veya veri bütünlüğü için tek başına yeterli değildir.
- Kimlik doğrulama ile yetkilendirmeyi ayrı uygulayın. Giriş yapmış olmak, kullanıcının başka bir kullanıcıya ait
/api/tasks/42kaydını okuyabileceği veya değiştirebileceği anlamına gelmez. - HTTPS kullanın, sırları kaynak koduna veya istemciye gömmeyin ve API anahtarlarını günlük kayıtlarına yazmayın.
- Her nesne erişiminde sahiplik veya rol kontrolü yapın. Kullanıcının URL'de başka bir kimlik göndermesi, o nesne üzerinde işlem yapmaya yetkili olduğunu kanıtlamaz.
- Büyük istek gövdeleri, pahalı sorgular, toplu işlemler ve art arda gelen istekler için uygun kaynak ve hız sınırları koyun.
- Başarılı, hatalı ve yetkisiz senaryoları otomatik testlerle sınayın. Eksik alan, bozuk JSON, bulunamayan kayıt, başka kullanıcıya ait kayıt ve tekrar gönderilen istekleri özellikle test edin.
Bakım ve sık yapılan hatalar
İlk sürümde az sayıda ve net uç nokta oluşturun. Listeleme uç noktalarında sayfalama, filtreleme ve sıralama sınırlarını baştan tanımlayın; istemcinin sınırsız veri çekmesine izin vermeyin. Yanıt sözleşmesini değiştirirken mevcut istemcileri bozmayacak şekilde yeni alanları geriye dönük uyumlu ekleyin. Kırıcı değişiklik gerekiyorsa sürümleme ve kaldırma takvimini belgelendirin.
Yaygın hatalar her durumda
200 OK döndürmek, doğrulamayı yalnızca tarayıcıda yapmak, kimlik doğrulamayı yetkilendirme sanmak, istemcinin gönderdiği alanları doğrudan veritabanı modeline aktarmak ve tüm iç alanları yanıta koymaktır. Parolalar, gizli belirteçler ve istemcinin ihtiyacı olmayan kişisel veya dahili alanlar yanıta alınmamalıdır.Bir diğer hata da dış servisten gelen veriyi otomatik olarak güvenilir kabul etmektir. Harici API yanıtlarını da şema, boyut, zaman aşımı ve hata davranışı açısından kontrol edin. API dokümantasyonunu gerçek davranışla eşleştirin; dokümanda bulunan fakat sunucuda çalışmayan bir uç nokta istemci tarafında doğrudan entegrasyon sorununa dönüşür.
Sık sorulan sorular
API dokümantasyonu ne zaman hazırlanmalıdır?
İlk uç nokta kodlanmadan önce temel sözleşme hazırlanmalıdır. URL, metot, istek alanları, yanıt örnekleri, durum kodları ve yetki gereksinimleri önceden yazılırsa istemci ve sunucu ekipleri farklı varsayımlarla ilerlemez.
API'de mutlaka JWT kullanmak gerekir mi?
Hayır. Kimlik doğrulama yöntemi uygulamanın istemci türüne, tehdit modeline ve mevcut kimlik altyapısına göre seçilir. JWT yalnızca bir seçenektir; kullanılacak yöntemin saklama, yenileme, iptal ve yetki kapsamı kuralları ayrıca tasarlanmalıdır.
