REST API Notları ve İpuçları

İçindekiler

REST'e Giriş
HTTP Metodları
Durum Kodları
URI Tasarımı
İstek Başlıkları
Yanıt Başlıkları
İçerik Türleri
Kimlik Doğrulama
HATEOAS
Sürümleme
Önbelleğe Alma
En İyi Uygulamalar
Araçlar

REST'e Giriş

REST (Temsili Durum Transferi), ağ uygulamalarını tasarlamak için bir mimari stildir. Genellikle HTTP olan durumsuz, istemci-sunucu iletişim protokolüne dayanır.

Temel ilkeler:

İstemci-Sunucu mimarisi
Durumsuzluk
Önbelleğe alınabilirlik
Tekdüze Arayüz
Katmanlı Sistem
İstek Üzerine Kod (isteğe bağlı)

HTTP Metodları

GET     : Bir kaynağı almak
POST    : Yeni bir kaynak oluşturmak
PUT     : Mevcut bir kaynağı güncellemek (tam güncelleme)
PATCH   : Mevcut bir kaynağı kısmen güncellemek
DELETE  : Bir kaynağı silmek
HEAD    : GET'e benzer ancak yanıt gövdesi olmadan
OPTIONS : Hedef kaynak için iletişim seçeneklerini açıklamak

Durum Kodları

1xx : Bilgilendirici
2xx : Başarılı
3xx : Yönlendirme
4xx : İstemci Hatası
5xx : Sunucu Hatası

Yaygın kodlar:
200 OK                  : İstek başarılı
201 Created             : Yeni kaynak oluşturuldu
204 No Content          : İstek başarılı, içerik döndürülmedi
400 Bad Request         : Geçersiz istek
401 Unauthorized        : Kimlik doğrulama gerekli
403 Forbidden           : Sunucu anladı ancak yetkilendirmeyi reddediyor
404 Not Found           : Kaynak bulunamadı
405 Method Not Allowed  : Bu kaynak için HTTP metodu desteklenmiyor
500 Internal Server Error: Genel sunucu hatası

URI Tasarımı

https://api.example.com/v1/kaynaklar/{id}

- Fiil değil, isim kullanın
- Koleksiyonlar için çoğul isimler kullanın
- Okunabilirliği artırmak için kısa çizgi (-) kullanın
- Küçük harfler kullanın
- Dosya uzantılarını dahil etmeyin

Örnekler:
GET     /kullanicilar          : Tüm kullanıcıları listele
GET     /kullanicilar/123      : ID'si 123 olan kullanıcıyı al
POST    /kullanicilar          : Yeni bir kullanıcı oluştur
PUT     /kullanicilar/123      : 123 numaralı kullanıcıyı güncelle
DELETE  /kullanicilar/123      : 123 numaralı kullanıcıyı sil
GET     /kullanicilar/123/siparisler : 123 numaralı kullanıcının siparişlerini al

İstek Başlıkları

Accept          : İstenen içerik türünü belirt
Authorization   : Kimlik doğrulama bilgilerini sağla
Content-Type    : İstek gövdesinin medya türünü belirt
User-Agent      : İstemci uygulamasını tanımla
Cache-Control   : Önbelleğe alma yönergelerini belirt

Yanıt Başlıkları

Content-Type    : Yanıt gövdesinin medya türünü belirt
Cache-Control   : Önbelleğe alma yönergelerini belirt
ETag            : Kaynak için bir sürüm tanımlayıcısı sağla
Location        : Yeni oluşturulan kaynağın URL'sini belirt

İçerik Türleri

Yaygın MIME türleri:

application/json
application/xml
application/x-www-form-urlencoded
multipart/form-data
text/plain

Kimlik Doğrulama

Yaygın kimlik doğrulama yöntemleri:

Temel Kimlik Doğrulama:
Authorization: Basic base64(kullanici_adi:parola)

Taşıyıcı Belirteci:
Authorization: Bearer <belirtec>

API Anahtarı:
X-API-Key: <api_anahtari>

OAuth 2.0:
Authorization: Bearer <erisim_belirteci>

HATEOAS

HATEOAS (Uygulama Durumunun Motoru Olarak Hipermedya), REST uygulama mimarisinin bir kısıtlamasıdır.

HATEOAS ile örnek JSON yanıtı:

{
  "id": 123,
  "ad": "Ahmet Yılmaz",
  "bağlantılar": [
    {
      "rel": "kendisi",
      "href": "https://api.example.com/kullanicilar/123"
    },
    {
      "rel": "siparisler",
      "href": "https://api.example.com/kullanicilar/123/siparisler"
    }
  ]
}

Sürümleme

Yaygın sürümleme stratejileri:

URI Sürümleme:
https://api.example.com/v1/kullanicilar

Başlık Sürümleme:
Accept: application/vnd.example.v1+json

Sorgu Parametresi Sürümleme:
https://api.example.com/kullanicilar?versiyon=1

İçerik Türü Sürümleme:
Content-Type: application/vnd.example.v1+json

Önbelleğe Alma

Cache-Control başlık yönergeleri:

Cache-Control: max-age=3600
Cache-Control: no-cache
Cache-Control: no-store
Cache-Control: private
Cache-Control: public

ETag kullanımı:

Yanıt:
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Sonraki İstek:
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

En İyi Uygulamalar

HTTPS kullanın
API'nizi sürümleyin
Kaynak koleksiyonları için çoğul isimler kullanın
Kapsamlı dokümantasyon sağlayın
Açıklayıcı mesajlarla uygun hata yönetimi uygulayın
Büyük veri setleri için sayfalama kullanın
Filtreleme, sıralama ve arama desteği sağlayın
Hız sınırlaması uygulayın
Uygun HTTP durum kodlarını kullanın
API'nizi durumsuz yapın
Keşfedilebilirlik için HATEOAS uygulayın
Varsayılan veri formatı olarak JSON kullanın
Uygun kimlik doğrulama ve yetkilendirme uygulayın
Önbelleğe alma mekanizmaları kullanın
API çağrılarını toplu halde yapmanın bir yolunu sağlayın

Araçlar

Postman - API geliştirme ve test etme
Swagger - API dokümantasyonu ve tasarımı
cURL - HTTP istekleri yapmak için komut satırı aracı
JSONLint - JSON doğrulayıcı
JSON Editor Online - JSON düzenleyici ve biçimlendirici
Insomnia - REST istemcisi
Apache JMeter - Yük testi ve performans ölçümü
Charles Proxy - Hata ayıklama için HTTP proxy
Fiddler - Web hata ayıklama proxy'si
REST-assured - REST servislerini test etmek ve doğrulamak için Java DSL