REST API Geliştirme ipuçları ve en iyi uygulamalar - Bölüm 1

Giriş ve planlama

Bu, REST API'lerinde üç yazı dizisinin ilkidir.

• Bölüm 1: Giriş ve planlama
• Bölüm 2: Şema önerileri, yaygın hatalar ve itiraz
• Bölüm 3: Belgeleme ipuçları ve temel bilgilerin ötesine geçme

GİRİŞ

REST API'leri bugünlerde her yerde. Şebeke destekli uygulamalar geliştiriyorsanız, olasılıkla kodunuzda en az bir tane tüketmiş olmanız ve muhtemelen kendinizden bir tane yazmak üzere olduğunuz için bunu okuyorsunuz demektir.

Bu seri nedir ve ne değildir

Bu yazı dizisi REST'e giriş değildir. REST'in ne olduğunu ve neyi başarmayı hedeflediğini net bir şekilde anladığınızı varsayar. Ayrıca, Web API tasarımı ve geliştirmesi hakkında kapsamlı bir En İyi Uygulamalar makalesi değildir. Zaten çevrimiçi olanların birçoğu var ve olabildiğince çok okumanı öneririm.

Çoğunlukla, insanların REST API'lerini tasarlarken ve uygularken yaptıkları çok yaygın ve gözden kaçan hataların bir listesidir. Biliyorum, sadece onlarla diğer insanların API'lerinde karşılaştığım için değil, bazılarını kendim yaptığım için biliyorum. :)

Bu neden yazılmış

Mükemmel bir dünyada, bir REST API geliştirdikten hemen sonra yapması gereken ilk şey, bunun için bir istemci uygulaması yazmaktır. API'nizin gerçek bir kullanım durumundan ziyade, insanların arayabileceği bir uç nokta listesi olan bir UI'den bahsetmiyorum. Yaratıcılığınızın verimsizliğini ortaya çıkaracak, onu kendiniz doğru kullanmak zorunda kalmaktan başka bir şey yok. Bunu biliyorum çünkü onlarca kez yapmak zorunda kaldım.

Dünyamız elbette mükemmel değildir ve çoğu zaman bir arka uç geliştiricinin API uygulamasını tamamladıktan sonra başka şeylere geçmesi gerekir, ancak yalnızca API tüketicileri onu kendi istekleri için geri çağırmak zorunda kalana kadar günahlar. Ben de çoğu zaman o mutsuz pozisyondayım, bu yüzden umarım hatalarım ve ipuçlarım zamandan tasarruf etmenize yardımcı olur - böylece yeni özellikler ekleme zamanına kadar API kodunuza geri dönmeniz gerekmez.

PLANLAMA

Nazikçe Dan Bickell tarafından sağlanan görüntü

1. Başlamadan önce

Bulabildiğiniz kadar REST API tasarım ve geliştirme belgesi ve kitabı okuyun! Burada fiil URI'leri yerine isim kullanma (ayy, şimdi yaptım…) vb. Gibi ortak ipuçlarından bahsetmeyeceğim, çünkü bunun nedeni, başka bir yerde daha önce okuduğunuzu farz ediyorum.

Alternatifleri düşünün

REST bir paradigma olarak oldukça popülerdir, ancak bir çok tadı geliyor. Devam etmeden önce, olabildiğince çoğuna bir göz atmalısınız. Bunu yaparken, sadece belirli kullanım durumları için harika görünen, aynı zamanda Facebook (geliştiren) ve GitHub’ın yeni v4 API’si tarafından da kullanılan tamamen farklı bir yaklaşım olan GraphQL’i kontrol etmeyi unutmayın.

Başkalarının ne yaptığını görün

Saygın kuruluşlardan mümkün olduğunca çok sayıda popüler API kullanmaya çalışın. İşte başlamanız için birkaç adım: GitHub, Çizgili, Twitter, PayPal

2. Vakıf

API'nizin küçük kalacağını varsaymayın - neredeyse hiç olmaz. Bunu kendi müşteri uygulamanız için kullanan tek kişi olsanız bile, kısa bir süre sonra ekstra bir son noktaya, sayfalama, analitik, bir test moduna ve başka nelerin olduğunu bilenlere ihtiyacınız olacak ve uygulamanız popüler hale gelmeden ve diğer insanlar başlamadan API’nize erişim istiyoruz…

Tamam - belki bu bir gerginliktir; Ancak, genellikle yazılım geliştirmede olduğu gibi, erken bir temel atmazsanız, uzun vadede çok pahalıya ödersiniz. API'lerin kolayca tüketilebilir olmak için tutarlı olmaları gerektiğinden, koli bandı kullanarak kendilerine özellik eklemeye çalışmak yalnızca sizin için değil, müşterileriniz için de işleri zorlaştırır.

Ayrıca, işleri daha iyi durumda tutma konusunda ne kadar iyi olursanız, tamamlamaları o kadar az zaman alır ve çok kısa sürede…

3. belirtimi

Güçlü bir temel hakkında konuşmak; Aslında kod yazmaya başlamadan önce API'niz için şartname oluşturmaya çalışın. Daha önce yapmadıysanız çok sıkıcı geldiğini biliyorum, ancak uzun vadede karşılığını öder ve size zaman ve zorluk kazandırır.

OpenAPI Şartnamesi (OAS - eski adıyla Swagger), gittikçe daha fazla organizasyon ve alternatif üzerinde birleştiği için şu an gitmenin en popüler yolu gibi görünüyor. Alternatif olarak, Postman harika bir API geliştirme ortamıdır, ancak yalnızca bireyler veya küçük geliştirici ekipleri için ücretsizdir.

Yalnızca kullanacağınız küçük bir dahili API geliştirmiyorsanız, bu ipucunu dikkate almamanızı şiddetle tavsiye ederim.

4. Sürüm

Çevrimiçi olarak bu konuyla ilgili birçok özel kaynak olduğundan, bu gönderideki farklı sürüm yaklaşımlarına odaklanmayacağım. Güçlü bir versiyonlama yaklaşımı seçmenin ve onu dini olarak takip etmenin ne kadar önemli olduğunu vurgulamaya çalışacağım. Ayrıca yıllar boyunca bana iyi hizmet eden bir yaklaşım sunacağım.

Neden önemli

Güçlü bir versiyonlama yaklaşımı, tüketicilerinize (ve dolayısıyla son kullanıcılarınıza) gönül rahatlığı sağlar, çünkü API değişikliklerinin mevcut müşteri uygulamalarının işlevselliğini bozmasını önler. İstemci uygulamaları kendileri aynı geliştirici veya API ile aynı kuruluş tarafından geliştirilse bile, kullanımdan kaldırılmış istemcilerin bir API güncellemesi mevcut olduğunda kullanımda olabileceği birçok senaryo vardır.

Bu olayın çok yaygın bir şekilde ortaya çıkması, geliştiricilerin nadiren güncelleme döngüsünün tam kontrolünde olduğu mobil veya masaüstü işletim sistemi istemci uygulamalarıdır. Müşteri güncelleme mekanizmalarınız ne kadar iyi ve otomatik olursa olsun, kullanıcılarınızın müşteri uygulamalarınızın en son sürümünü çalıştırdıklarından neredeyse% 100 emin olamazsınız.

iOS, varsayılan olarak etkinleştirilmiş uygulamalar için çok güvenilir bir otomatik güncelleme mekanizmasına sahiptir, ancak bir kullanıcının tercihlerine ve ağ durumuna bağlı olarak, cihazlarının bir sonraki çalıştırılışında müşteri uygulamanızı güncelleme şansına sahip olmayabilir. Aynı durum Android'in daha yeni sürümleri için de geçerlidir, eski sürümlerin ise uygulama güncellemelerinde çok geride kalması daha muhtemeldir.

Öte yandan, masaüstü uygulamaları otomatik güncelleme mekanizması sağlayabilir veya sağlamayabilir - ancak bunlar çoğu zaman tercih edilir ve hemen güncellemeye izin vermeyen durumlar (kuruluş ortamları gibi) vardır. Tarayıcı istemci uygulamaları bile (ve çoğu durumda) arka uçlarından ayrılabilir ve bu nedenle API'den tamamen farklı bir sürüm döngüsüne sahip olabilir.

Tüketici değişikliklerinizi iletin

En iyi versiyonlama sistemine sahip mükemmel bir API'niz olsa bile, tüketicilerinizin potansiyelinin tam olarak farkında değillerse hepsi bir anlam ifade etmiyor. Değişikliklerin ve yeni özelliklerin iletilmesi, kullanıcılarınızın bunlardan tam olarak yararlanabilmesi için çok önemlidir. Daha da önemlisi, kullanıcılarınızı kullanımdan kaldırılacak veya kaldırılacak konular konusunda yeterince erken uyarmaktır, bu nedenle müşterilerinin yeni sürümlerini güncellemek, test etmek ve göndermek için yeterli zamanları vardır.

Güncel bir dokümantasyon tutmak ve her sürüm için ayrıntılı değişiklikler yayınlamak çok önemlidir ve geliştirme döngünüzün bir parçası olmalıdır.

Büyük / küçük versiyon yaklaşımı

Yıllar boyunca çok takdir ettiğim bir versiyonlama yaklaşımı, büyük / küçük bir versiyon şemasıdır. API’niz (eğer doğru şeyler yaparsanız) sadece değişikliklerin değiştiği durumlarda güncellenen ana sürüm numarası ve küçük eklemeler olduğunda her zaman güncellenen küçük sürüm numarası ile karakterize edilir.

Başka bir açıdan bakıldığında, her bir ana sürüm, API kaynaklarının ve şemanın yapısının, bu arada kaç küçük sürüm yayınlandığına bakılmaksızın, yaşam döngüsü boyunca bozulmayacağını garanti eder. Küçük versiyonlar geriye dönük olarak uyumludur.

Ana sürümün, API’nin temel URL’sinin bir parçası olması (ör. Https://api.myserver.com/v1/endpoint) ve küçük sürümün, bir istek başlığı aracılığıyla seçilebilmesi yaygındır. İstek üstbilgisi sağlanmadığında, en son küçük sürüm kullanılır. Bu yaklaşımı izleyen pek çok popüler API var, en sevdiğim şey Stripe (küçük sürümler için çıkış tarihleri ​​kullanan).

Aşağıdaki bölümlerde API'nizde yapılan güncellemelerden bahsederken bu yaklaşımdan tekrar bahsederken, gereksinimlerinize en uygun kendi resmi versiyonlama sisteminizi seçmek size kalmış. Sadece hatırlayın, bir kere yaparsanız, buna bağlı kalmanız gerekecek.

5. Test

Prodüksiyon'da değilken bu iyidir

Genel olarak, yazılım geliştirme sürecinin ayrılmaz bir parçası olarak, API'niz için test gereklidir. API'ler genellikle sunucu olan gerçeğin tek kaynağı olan gerçeğe bağlı kaynak ile bir veya daha fazla müşteri uygulaması arasındaki bağlantıyı oluşturduğundan, her koşulda güvenilir olmaları gerekir ve hiçbir şekilde parçalanmış üretime girmeleri göze alınmaz. Ayrıca, genellikle ağa maruz kaldıklarından ve bu nedenle çok sayıda riske maruz kaldıklarından, çok sayıda ortak ve yaygın olmayan senaryolar için ayrıntılı olarak test edilmeleri gerekir.

Uç noktalarınızı Swagger, Postacı veya REST konsolu gibi araçlar kullanarak arayarak yapılan manuel testler, çeşitli temel özellikleri test etmeye devam ettiğinizde, yalnızca bebeğin gelişiminin ilk aşamalarında size yardımcı olabilir. Erken bir otomatik test grubunu korumak, bitmiş ürünün kalitesi için bir dünya yaratıyor.

Yapıları gereği, API'ler fonksiyonel testler için ideal adaylardır. İç uygulamalarını test eden bir birim çok önemlidir (diğer herhangi bir yazılım için olduğu gibi) ancak bence, bir API'yi işlevsel olarak test etmek ve kara kutuya benzetmek, harcayacağınız zaman için çok daha fazla değer sağlar.

Test sırasında kurabileceğiniz ve parçalayabileceğiniz bir test veritabanının bakımı, işlemin önemli bir parçasıdır. Geçmiş sorunlara katkıda bulunan verileri (geliştirme sırasında gözlemlenen veya tüketicileriniz tarafından rapor edilen) eklemeye devam edin ve bu hatalardan bir kez ve hepsinden kurtulduğunuzdan emin olmak için test takımınızı regresyon testleriyle zenginleştirin.

Giriş parametrelerinin onaylanmasının, en garip vakaları bile test edene kadar tamamlandığını asla varsaymayın (müşteri uygulamalarınızın kendileri için oldukça zorlayıcı olabileceğini unutmayın). Son olarak, kalan az çalışma zamanı hatalarını yakalamak, tüketici davranışlarını gözlemlemek ve daha fazla test senaryosu oluşturmak için bu bilgileri kullanmak için uygun bir kayıt altyapısına zaman ayırın.

6. Dağıtım

Daha önce fark etmiş olabileceğiniz gibi (veya okumaya devam ederken farkedeceğiniz gibi), bu yayın yoğun bir şekilde bir şeyleri bozmayan bir API oluşturmaya odaklanır. Neredeyse tüm yazılım ürünlerinde işleri kırmanın en korkunç aşaması elbette dağıtımdır.

Çoğu durumda, doğru bir şekilde sınama ve sürüm yapma işlemini tamamladıysanız, dağıtım sırasında bir sorunla karşılaşma olasılığı çok düşüktür; Bununla birlikte, işte ekstra yardım olabilecek birkaç ipucu.

Her şeyi ayır

İşte çok yaygın bir senaryo:

API'niz, harici kuruluşlar tarafından geliştirilen birkaç B2B müşterisine veri sağlar, birkaç mobil uygulama ve kendi kuruluşunuz tarafından geliştirilen bir web uygulaması sunar ve aynı zamanda web üzerinden erişilebilen bir sunucu uygulamasının ayrılmaz bir parçasıdır. , yönetim amaçları için.

Kulağa karmaşık gelebilir, ancak geçmişte birçok kez daha basit veya daha karmaşık varyasyonlarda gördüm. Buradaki kilit nokta, API'nin bir organizasyonun temel taşı olmasına rağmen, sıklıkla diğer sorumlulukları olan en az bir sunucu uygulamasıyla sıkı bir şekilde bağlantılı olmasıdır.

Bu, sunucu uygulamasını güncelleme zamanı geldiğinde, bir şey bozulursa, API'nin de kırılması olasılığının yüksek olduğu anlamına gelir. Bu durumda, API tüm tüketicilerini onunla birlikte düşürür ve sonunda son kullanıcıların gazabı şirkete iner.

Kullanıcılarınızı rahatsız etmek en son istediğiniz şeydir

Bu bağlamda sıkı birleşmenin bir başka eksikliği, bir uygulamanın serbest bırakma döngüsünün diğerlerini etkilemesidir. Bu, karmaşık planlama ve dağıtımların düzenlenmesi gerektirir. Dahası, iş açısından bir anlam ifade etmiyor (her uygulama kendi iyi zamanında yayınlanmalı - gerisini etkilemeden).

API'niz ve uygulamalarınızın geri kalanı altyapınızın bağımsız modülleri olarak geliştirilirse, bunların tümü ortadan kalkar. Birisi, daha fazla ayrı modüle sahip olmanın daha fazla başarısızlık noktası anlamına geldiğini iddia edebilir, ancak bunun doğru versiyonlama ve testlerle çözülebileceği söylenebilir. Ayrıca, API'nizin yeni sürümü dağıtıma son verdiyse bile, ekibiniz ilk bilen kişi olacaktır. Bu durumda, daha iyi bir şey yapılamazsa, her şeyin doğru çalıştığından emin olana kadar müşterilerinizin sürümlerini her zaman birkaç gün geciktirebilirsiniz.

Zorlu testlerle korunmanız gereken tehlikeli durumlardan biri, sunucu uygulamanızın yeni sürümünün API'nizin mevcut sürümünü kırmasıdır. Yine, bundan kaçınmanın tek yolu (elbette) uygun versiyonlama ve test ile sıkı bir geliştirme sürecidir. Altyapınızın tüm bölümlerini ayrı modüller olarak ele almak, bu yaklaşımı daha da teşvik eder.

7. (Zarif) İtiraz

Bir süre sonra, uygulamanız olgunlaştıkça, API'nin mevcut ana sürümünüzü yenisinin lehine kaldırmanız kaçınılmazdır. Halen geliştirilme aşamasında olan istemci uygulamalarının da yeni sürüme yükseltilmesi gerekir, ancak bu zaman alabilir.

Ayrıca, geliştiricilerin derhal hareket etmesinin bile istemci uygulamalarında anında güncelleme yapılması anlamına gelmediği durumlar vardır. Web uygulamalarının güncellenmiş sürümleri, piyasaya sürüldükten sonra son kullanıcılara sunulabilirken, mobil ve yerel işletim sistemi uygulamalarının eski sürümleri uzun süre kalmaya devam eder. Bazı kullanıcılar, telefonlarındaki veya bilgisayarlarındaki uygulamaların güncelleme işlemini gerçekten anlamıyor (veya farkında bile değil). Bu uygulamalar aniden bozulmaya başlarsa, kullanıcıların yanıtları yalnızca onları kullanmayı bırakmak olabilir.

Ana API sürümünün kullanımdan kaldırılması, hizmetin kesilmesi anlamına gelmemelidir. Kullanımdan kaldırılan sürüm tam olarak olduğu gibi çalışmaya devam etmeli, bir süre (mümkün olduğunca uzun süre) açıkça ve tekrar tekrar (sonuna yaklaştığı gibi) tüketicilerinize iletilecektir. İdeal olarak, API’nizin eski sürümleri, güvenlik riski oluşturmadıkça veya arka planınıza zarar vermediği sürece çalışmayı bırakmamalıdır.

8. Genellikle göz ardı edilen iyi uygulamalar

Kaynaklar için çoğul veya tekil formları kullanabilirsiniz, ancak ikisini birden kullanamazsınız.

/ arabalar gayet iyi ve / araba da öyle ama ikisini de kullanamazsınız. Bir form seçin ve API'niz boyunca ona bağlı kalın. Olmazsa, tüketicilerinizi ve hatta gelecekte kendi geliştiricilerinizi ya da kendinizi bile şaşırtacaksınız.

PUT ve PATCH yanıtlarında güncellenmiş nesneleri döndür

PUT veya PATCH fiiller aracılığıyla yapılan başarılı bir talepten sonra, müşterinin genellikle güncellenmiş kaynağın durumunu bilmesi gerekir. Birden fazla müşterinin aynı anda güncelleme yapması oldukça mümkün olduğundan, güncelleme gerçekleştiği anda her birinin kaynağın durumu hakkında bilgilendirilmesinin tek yolu budur.

Çerezler ve PHPSESSIONID

Bu, PHP tarafından geliştirilen uygulamalarda çok yaygındır. API kendi özel kimlik doğrulama belirtecini kullanır, ancak PHP’nin varsayılan oturum işlemlerini kullanan geliştiricinin haberi olmadan, tüm yanıtlarda ayrıca korkunç PHPSESSIONID çerezleri de bulunur! Bu, uzun vadede her türlü böceğe neden olur, çünkü hiç kimse (geliştirici dahil) çerez hakkında bilgi sahibi değildir, çünkü kimse onu koyduğunu düşünmez.

Çerezler, genel olarak, REST tarafından açıkça yasaklanmamaktadır. Yanlış kullanıldığında sorun yaratabilirler (örneğin, API mekanizmanızla da yetkilendirilmesi gereken ayrı bir alana erişmeye çalışırsanız), ancak şartnameyle yasaklanmadılar. Kaçınılması gereken, aynı anda birden fazla kimlik doğrulama şekli kullanmaktır.

PHP’nin oturum işlemleriyle ilgili olarak, PHPSESSIONID çerezinin API’nizin kimlik doğrulama belirteci olarak davranmasını istemiyorsanız (hiçbir şekilde önermem!), Asla API’nizin varsayılan PHP çerez yaklaşımına güvenmemelisiniz. Tavsiyem, tercih ettiğiniz kimlik doğrulama yöntemini uygulayan özel bir oturum işleme mekanizması uygulamak olacaktır.

Dahili hataları veya uygulama ayrıntılarını gösterme

Yıllar boyunca bunu sayısız durumlarda, büyük şirketlerin popüler API'lerinde bile gördüm. Yanıtlarınızdaki iç (SQL gibi) hataları açığa vurmak harika bir şey değil! Bunları ileride başvurmak üzere günlüğe kaydetmenin güvenilir bir yolunu bulun, ancak bunları API yanıtlarınızda genel 500 - Dahili Sunucu Hatası'na çevirin.

Zorunlu xkcd - her zaman alakalı.

Bu gelişme sürecinde erken yapmanız gereken ilk şeylerden biridir. Güvenlik, web’de sunulan bir hizmet için çok önemli bir endişe olmalıdır.

Bu, REST API'lerindeki üç gönderi serisinin ilkidir.

Bir sonrakini buradan okuyabilirsiniz:
Bölüm 2: Şema önerileri, yaygın hatalar ve itiraz