REST API'leri, modern yazılım uygulamalarının büyük bir çoğunluğu olarak, web hizmetleri için standart mimari tarzı olarak hizmet vermektedir. Yazılım mühendisleri için, REST API tasarımı istenmiyor - doğrudan etkiler sistemi güvenilirlik, ölçeklenebilirlik ve geliştirici deneyimine sahip olmak için doğru bir yetenektir. Kötü tasarlanmış API, kabuslar için teşvik eder ve ağır bakım maliyetlerine yol açar.

Bu makale REST'nin temel prensiplerini inceler ve API geliştirme sırasında ortaya çıkan en yaygın tasarım soruları keşfeder ve gerçek dünya üretim sistemlerindeki en iyi uygulamaları sağlar.

Bir REST API nedir?

REST, 0:0)Representational State Transfer[DÜT:1) için, 2000 doktora tezlerinde Roy Fielding tarafından tanıtıldı.Anada, REST API, müşterilerin ve sunucuların HTTP üzerindeki verileri nasıl değiştirdiğini yöneten bir kısıtlamadır.

REST API'ler devletsizdir, yani bir müşteriden gelen her istek, sunucunun bunu işlemesi gereken tüm bilgileri içermelidir. sunucu istekler arasında oturum açma durumunu saklamaz, çünkü herhangi bir sunucu örneği paylaşılan oturum hafızaya güvenmeksizin herhangi bir istekle idare edebilir, ancak aynı zamanda sohbet durumunu yönetmek için müşteri üzerinde daha fazla sorumluluk tutabilir.

REST köklerinin sadeliği, performans ve ölçeklenebilirliğinden popülerliği. Ubiquitous HTTP protokolünden faydalanır, tanıdık yöntemler kullanır ve JSON gibi hafif formatlarda verileri döndürür.For software mühendisler için, anlayış REST derinden sezgisel, içilebilir ve koruyabilirsiniz, kamuya açık bir API veya iç bir mikro hizmet inşa edebilirsiniz.

REST API Design

REST, altı mimari kısıtlamayı tanımlar. Tüm API'ler her kısıtlamaya sıkıca uymaz (bazılar puristten daha pragmatiktir), aşağıdaki ilkeler iyi REST API tasarımının temelini oluşturur.

Devletsizlik

Her müşteri isteği kendini barındırmalıdır. sunucu, herhangi bir istekle ilgili herhangi bir müşteri bağlamını saklamamalıdır. Bu, kimlik doğrulama Jetonları, istek parametreleri ve gerekli tüm veriler talepte açıkça belirtilmelidir. Devletsizlik önemli etkiler vardır: herhangi bir sunucu herhangi bir istekle başa çıkabilir, oturum tabanlı başarısızlık puanlarını kaldırarak güvenilirlik geliştirir ve caching istemcileri daha öngörülebilir hale getirir.

Kaynak-Based

Kaynaklar REST. A kaynağının bir nesnesi, bir nesne koleksiyonu olabilir veya hatta bir süreçtir. Her kaynak, standart bir kaynak kullanarak benzersiz bir şekilde belirlenir (URI). URIRID eylemlerine göre yapılır. Örneğin,INGFLT:0).

HTTP Yöntemleri Kullanımı

REST standart HTTP yöntemlerinin ayrı bir şekilde ayrılmasından faydalanır:

  • [FONT:0)GET[DÜT:1) - Bir kaynağa (güvenli ve idempotent) erişim.
  • [FONT:0)POST[DÜT:1] – Yeni bir kaynak oluşturun (dahadempotent değil).
  • [FONT=0)PUT[DÜT:1] - Mevcut bir kaynağı değiştir (idempotent).
  • [FONT:0)PATCH[[DÜT:1) – Kısmen bir kaynağı güncelle (gömürücüyümsüz değil).
  • [FONT:0)DELETE[[DFLT:1) - Bir kaynağı (iddiamiv) çıkarın.

Bu yönteme başvurmak, HTTP ile tanıdık herhangi bir müşterinin API ile her uç nokta için özel belgelere ihtiyaç duymadan etkileşime girebileceğini garanti eder. Ayrıca altyapı proxy ve önbelleklerin akıllı taleplerle başa çıkmalarını sağlar.

Temsil

Bir müşteri bir kaynak aldığında, sunucu bu kaynağın bir gösterimini döndürür.En yaygın temsil JSON, ancak XML, YAML veya hatta özel formatlar kullanılabilir. temsil, kaynak mevcut durumunu içerir ve bağlantıları içerebilir (HATEOAS) ilgili kaynaklarla etkileşime girer.

Üniforma Interface

Tek arayüz kısıtlaması, REST'nin en ayırt edici özelliğidir. Müşteriyi sunucunun iç uygulamalarından ayırır. Bu kısıtlama dört alt-konstraints'tan oluşur:

  • [FONT:0) Kaynakların Identification of resources[Döntilmiş: 1) - Her kaynak eşsiz bir URI'ya sahiptir.
  • [FONT:0)Resimler aracılığıyla kaynakların düzenlenmesi[Döneticiler) – Müşteriler temsilleri göndererek kaynakları manipüle ederler (örneğin, JSON gövdesi ile bir PUT isteği).
  • [FONT:0]Kendi kendine ait mesajlar[Dönemli mesajlar[Döncüler: 1 ) – Her istek ve cevap, anlaşılmak için yeterli bilgi içeriyor (örneğin, medya tipi başlıklar, durum kodları).
  • [FONT:0) Uygulama durumu (HATEOAS) ) motoru olarak HATEOAS (HATEOAS)[FONT) tarafından belirlenen eylemleri dinamik olarak keşfetmeleri için yönlendiren bağlantılar sağlar.HATEOAS nadiren tam olarak uygulanırken, API'lerin daha keşfedilebilir ve daha az tuzlu olması için size yardımcı olur.

Common REST API Design Questions

Endpoints Nasıl Yapılı Olmalı?

Endpoint tasarımı API tasarımının en tartışmalı yönlerinden biridir. evrensel olarak kabul edilen en iyi uygulama, [[0) Basit nouns[[Döntgen 1: 1) kaynak koleksiyonları için ve URIs'daki fiillerden kaçınmaktır.

  • [[Dönetici:2|kullanıcılar koleksiyonu
  • [[DÜDÜDÜ: 3) - tek bir kullanıcı
  • [[DÜDÜ:) Belirli bir kullanıcıya ait siparişler
  • [FONT: 5)

Derinlik sınırlı olmalıdır. İki veya üç seviyeden daha fazla olmak, koleksiyon için okumak ve korumak için URI'lar zorlaşır, sorgu parametrelerini veya özel kaynakları kullanmayı düşünün.*) HTTP yöntemi zaten harekete geçer: koleksiyon için kullanıyorsanız, başka bir koleksiyon için sorgulayıcı kullanın.

Hataları nasıl ele geçirebilirsiniz?

Hata cevapları bilgilendirici ve tutarlı olmalıdır. Doğru HTTP statüsünü kullanın:

  • [FONT=0)400 Kötü İstek[DÜDÜT:1) - Malformel istek (örneğin, gerekli alan, geçersiz JSON).
  • [FONT=0)401 Una yetkili) – Eksik veya geçersiz kimlik doğrulama.
  • [FONT:0)403 İzin[[Dönetici:0)[0]403 İzin[[Dönetici: 1 ) - Kimlik kartı eksik değildir.
  • [FONT:0)404 Bulunmamak[Dönemli değil.
  • [FONT=0)409 Çatışma[DÜDÜT:1] - Mevcut devletle çatışmaları talep edin (örneğin, tekrar giriş).
  • [FONT:0]422 İşsiz Birlik[Dönetici: 1) Talep gövdesinde doğrulama hataları.
  • [FONT=0)500 İç sunucu Hatası).

Durum koduna ek olarak, yanıt gövdesi tutarlı bir yapı içermelidir. Ortak bir model:

{
 "error": {
 "code": "USER_NOT_FOUND",
 "message": "User with ID 42 not found.",
 "details": "..."
 }
}

Makine hazırlanabilir bir hata kodu, insan hazırlanabilir bir mesaj ve isteğe bağlı olarak doğrulama hataları veya silme için bir iz ID sağlayın. Üretim yanıtlarında yığın izlerini açığa çıkarma.

What About Versioning?

API'ler gelişti. Versioning geri uyumluluk sağlar, böylece mevcut müşteriler yeni özellikler veya değişim davranışları eklediğinizde kırılmaz. Three common approach available:

  • [FONT:0]URI versiyonu[[Dönetici: 1 ) – Yoldaki sürümi (örneğin, 03: 00). Bu, en popüler yaklaşımdır, çünkü rotaya açık ve kolay. Ancak, çiftleri URL yapısına dönüştürür.
  • [FONT:0)Header sürümleme[[Dönetici: 1 ) - Özel bir istek başlığı kullanın (örneğin, 03:11). Bu, URI temiz tutar, ancak müşterilerin doğru bir şekilde ayarlamasını gerektirir.
  • [FONT=0)Query parametresi[[DÜT 1: 1)[[[Üye Olmayanlar İçin Tıklayınız.) Bu genellikle cesaret vericidir, çünkü sorgu dizeleri karıştırır ve caching ile müdahale edebilir.

URI versiyonu çoğu takım için en basit olanıdır. makul bir süre için versiyonlar tutun (en az iki yıl) ve onları açık iletişimle sil.

Pagination, Filtering ve Sorting'i nasıl uygulamalıyım?

Koleksiyon uç noktaları (örneğin, 03., 03.03.2012) binlerce kayıt geri verebilir. paginasyon olmadan, performans degradları ve ağ hava balonları.

  • [FONT=0)Pagination[[Dönetici:0)[[Dönetici:0))[[Dönetici: 9)))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))) · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
  • [FONT:0) Direktif[Dönetici:0)[Dönetici:0) Kaynaklama parametrelerini mantıksal olarak filtrelemek için kullanın. Örneğin, [[ŞUygunT:0) Consistly, uç noktaların aynı filtre modellerini uygular.
  • [FONT:0]Sorting[[Dönetici: 1)) - Mevcut sıralama için kullanılan parametrelerin veya [[Döneticileri) ile sıralamasına izin verin.

Bu işlemleri başlangıçtan destek, tüketicilerin kaçınılmaz olarak onları talep ettiğinden sonra tekrar faktör uç noktaları yeniden denemenizi engeller.

Kimlik ve Yetki Nasıl Çalışılır?

REST API'leri devletsizdir, bu yüzden doğrulama her istekle yapılmalıdır. En yaygın yaklaşım bazen yeterlidir.[FONTT:0bearer tokens) anahtarını değiştirmeden kolayca geri dönemezler. OAuth 2.0, iç API'ler için endüstri standardıdır, API anahtarları (özel bir başlıkta geçiş) bazen yeterlidir, ancak daha zayıf bir güvenlik sunarlar, çünkü sızıntı anahtarı anahtar kendi anahtarını değiştirmeden kolayca geri alınabilir.

Yazarizasyon (Bir kullanıcı ne yapabilir) genellikle sunucunun kimlik ile ilişkili rolleri veya izinleri kontrol ederek uygulanır.Müşteride izin verme mantığını içermekten kaçının; her zaman sunucuda doğrulanır.

Idempotency

Idempotency, aynı isteği birden çok kez yapanların, yan etkiler olmadan aynı sonucu elde etmesini sağlar. [FONT:0) ⁇ [/FONT][/FONT][/FONT=DELET:2}[DELET: 5 ), her seferinde yeni bir kaynak yaratır.[DELETEDELETED)[DELET:6)[DFLT:0)))))

Caching Nasıl Yönetilir?

Caching performans geliştirir ve sunucu yükü azaltır. HTTP caching, istemci ETag ile ilgili başlıklar tarafından yönetilir ve sunucu, değiştirilmezsen emin olur.

HATEOAS'a mı, yoksa HATEOAS'a mı değil?

HATEOAS ( Uygulama Devleti Motoru olarak) genellikle REST'nin anahtar farklılaştırıcısı olarak ifade edilir, ancak müşteri ve sunucu arasındaki bağlantıları daha da keşfedebilir ve azaltılabilir. Örneğin, bir kullanıcı kaynağı gerekli olan API'yi gezinmek için bağlantı sağlar.

REST API Design için en iyi uygulamalar

Bireysel soruları cevaplamanın ötesinde, tutarlı bir uygulama en iyi uygulamaları uygulama API'nizi sadece mükemmelliğe yükseltmektedir.

Tüm Konsiyonların Her Şeyi

Tek bir isim kontamine, cevap yapıları ve tüm uç noktaları boyunca davranışları kullanın.Bir uç nokta eksik bir kaynak için 404 döndürürse, hepsi JSON anahtarları için yılan case kullanırsa, her uç noktanın. Inconsistency frustrates geliştiricilerine ve entegrasyon süresini artırır.

Kapsamlı Dokümantasyon Sağlamak

İyi belgeler, Swagger/OpenAPI gibi bir API'nin ayrılmaz bir parçasıdır, [[Dönerge[Döntgenler:0)Directus[Dönemli API belgeleri içeren), ve Postman koleksiyonları geliştiricilerin son noktalarınızı hızlı bir şekilde anlamalarına yardımcı olur. Doküman istek/response örnekleri, hata kodları, oran sınırları ve doğrulama akışları. Gerçek API ile senkronize etmeyi tutun.

Standart HTTP Durum Kodlarını Kullanın

Müşteri hataları için 200 veya 500 $ kullanmayın. Proper statüsü kodları, müşterilerin başarı veya başarısızlık programını algılamasını kolaylaştırır.Reer to theENFLT:0)MDN statüsü kodu referansı[DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD) olarak kılavuz olarak kullanılabilir.

Güvenli Her Endpoint

Uygulama doğrulama ve yetki erken kullanın HTTPS sadece sunucu tarafında her girişi geçerlidir - istemciye güven.Sağlama işlemleri için sınırlamayı uygulayın, onay belirteçleri veya ÖSSF benzeri modeller gibi başka bir doğrulama gerektirir.

Tüketici için Tasarım

API'nizi kullanacak bir geliştirici perspektifinden düşünün. İç uygulama ayrıntıları (örneğin, URIs'taki veritabanı kimlikleri) anlamlı bir hata mesajları sağlayın.Test için bir geliştirici portal veya kumbox ortamı sağlayın.Plats veya müşteri kütüphanelerini popüler diller için teklif edin.

Evrim Planı

API'ler canlı ürünlerdir. kırma değişiklikleri tahmin etmediyseniz bile sürüm kullanın. Küçük sürümlerde kırılma değişiklikleri tanıtmaktan kaçının.Deprecate endpoints yumuşak: add aİLRAT:31Conding in specify when an endpoint will be removed, and keep old versions operational for a geçiş dönemi.

Sonuç Sonuç Sonuç Sonuç Sonuç Sonuç Sonuç Sonuç

REST API tasarımı hem bir sanat hem de bir bilimdir. Yazılım mühendisleri yüz yüze - uç nokta yapısı, hata işleme, sürümleme, paginasyon, güvenlik ve daha fazlası - rastgele engeller değildir.

Sonraki API'nizi tasarlarken, [FONT:2) ve aynı zamanda pragmatizm ile saflık ve dengeyi dengelemek için aşağıdaki geliştiricilerin daha basit, tutarlı ve saygılı olması gerekir.