Harika Web API Tasarımı için 5 Altın Kural

Kendinizi “ne düşündüklerini” merak ederken buldunuz mu? API aracılığıyla bir web hizmetini entegre ederken? Değilse, benden çok daha şanslısın.

Herhangi bir yazılım geliştiricisi, bir projenin spagetti koduna dönüşmesine izin vermenin ne kadar kolay olduğunu bilir ve web API'leri, karışık bir web ile sonuçlanmaya daha az eğilimli değildir. Ama böyle olması gerekmiyor. Gerçekte, insanların kullanmaktan gerçekten keyif alacağı ve sizin de oluşturmaktan keyif alacağınız harika web API'leri tasarlamak mümkündür. Ama nasıl? Bu sorunun cevabı bu yazının konusu.

Perspektif

Çözümler oluştururken çoğu zaman, programcı olmayan veya genellikle teknik olarak karmaşık olmayan son kullanıcılar için tasarım yaparsınız. Onlara grafiksel bir arayüz veriyorsunuz ve eğer işinizi doğru yapıyorsanız, onlardan arayüzün ne yapması gerektiğine dair oldukça iyi bir fikir edindiniz.

Ancak API geliştirme farklıdır. Muhtemelen kim olduklarını bile bilmeden programcılar için bir arayüz tasarlıyorsunuz. Ve kim olurlarsa olsunlar, yazılımınızdaki her küçük kusuru gösterecek teknik bilgiye sahip olacaklar (ya da en azından teknik bilgiye sahip olduklarını düşünecekler). Kullanıcılarınızın sizin API'niz için sizin API'niz kadar eleştirel olması muhtemeldir ve onu eleştirmekten tamamen zevk alacaklardır.

Ve bu arada, ironinin bir kısmı burada yatıyor. Kullanımı kolay bir web API'sinin nasıl yapıldığını anlaması gereken biri varsa o da sensin . Sonuçta, tıpkı API'nizin kullanıcıları gibi bir yazılım mühendisisiniz, dolayısıyla onların bakış açısını paylaşıyorsunuz. değil mi?

Pekala, onların bakış açısını kesinlikle anlasanız da, onların bakış açısını paylaşmak zorunda değilsiniz. API'nizi geliştirirken veya geliştirirken , bir API tasarımcısı perspektifine sahip olursunuz, oysa onlar bir API kullanıcısı perspektifine sahiptir.

API tasarımcıları genellikle "Bu hizmetin ne yapması gerekiyor?" gibi sorulara odaklanır. veya “Bu hizmetin ne sağlaması gerekiyor?” , API kullanıcıları "Bu API'yi ihtiyacım olanı yapmak için nasıl kullanabilirim?" , veya daha doğrusu, "Bu API'den ihtiyacım olanı elde etmek için minimum çabayı nasıl harcayabilirim?" .

Bu farklı sorular, iki büyük ölçüde farklı bakış açısına yol açar. Sonuç olarak, harika bir API tasarlamak için gerekli ön koşul, bakış açınızı API tasarımcısının bakış açısından API kullanıcısının bakış açısına kaydırmaktır. Başka bir deyişle, kendi kullanıcınız olsaydınız doğal olarak soracağınız soruları kendinize sürekli olarak sorun. API'nizin neler yapabileceğini düşünmek yerine, ihtiyaç duyabileceği veya kullanılmak isteyebileceği farklı yolları düşünün ve ardından bu görevleri API'nizin kullanıcıları için mümkün olduğunca kolay hale getirmeye odaklanın.

Bu kulağa kolay ve açık gibi gelse de, API'lerin bu şekilde tasarlanmasının ne kadar seyrek görüldüğü şaşırtıcıdır. Kariyerinizde karşılaştığınız API'leri düşünün. Bu perspektif akılda tutularak ne sıklıkla tasarlanmış görünüyorlar? Web API tasarımı zor olabilir.

Bunu söyledikten sonra, devam edelim ve Harika Bir Web API'si Tasarlamak için 5 Altın Kural hakkında konuşalım, yani:

1. belgeler
2. Kararlılık ve Tutarlılık
3. Esneklik
4. Güvenlik
5. Evlat Edinme Kolaylığı

Kural 1: Belgeler

Belgeler. Evet, buradan başlıyorum.

Belgelerden nefret mi ediyorsun? Pekala, empati kurabilirim, ancak "kullanıcı bakış açısı" şapkanızı takın ve bahse girerim belge yazmak zorunda kalmaktan daha çok nefret ettiğiniz tek şey belgelenmemiş bir API kullanmaya çalışmaktır. Sözümü bitirdim.

Sonuç olarak, herhangi birinin API'nizi kullanmasını istiyorsanız, belgeler çok önemlidir. Bunu doğru yapmanız yeterlidir. Kullanıcıların göreceği ilk şey bu, yani bazı yönlerden hediye paketi gibi. İyi sunum yapın ve insanların API'nizi kullanma ve herhangi bir tuhaflığa katlanma olasılığı daha yüksektir.

Peki iyi belgeleri nasıl yazarız?

Nispeten kolay kısım, API yöntemlerinin kendilerinin belgelenmesidir; yani, her ikisindeki öğelerin her birinin açıklamalarıyla birlikte örnek istekler ve yanıtlar. Neyse ki, belge oluşturma görevini kolaylaştıran ve basitleştiren artan sayıda yazılım aracı var. Veya API'nizi, uç noktalarınızı ve işlevlerinizi inceleyen ve sizin için ilgili belgeleri oluşturan kendiniz bir şeyler yazabilirsiniz.

Ancak harika belgeleri yeterli belgelerden ayıran şey, kullanım örneklerinin ve ideal olarak öğreticilerin dahil edilmesidir. Bu, kullanıcının API'nizi anlamasına ve nereden başlayacağına yardımcı olur. Onları yönlendirir ve API'nizi beyinlerine yüklemelerine yardımcı olur.

Örneğin, Twilio'nun geliştiricileri API'lerine her sınıfı, her yöntemi ve olası her yanıtı listeleyeceklerse, ancak SMS gönderebileceğinizi, bir aramayı takip edebileceğinizi veya bir telefon numarası satın alabileceğinizi söyleme zahmetine girmediler. API kullanıcısının bu bilgiyi bulması ve tutarlı bir şekilde anlaması gerçekten uzun zaman alacaktır. Adları dışında ne için kullanıldıklarına dair herhangi bir fikir sahibi olmadan dev bir sınıf ve yöntem ağacında sıralama yapmayı hayal edebiliyor musunuz? Kulağa korkunç geliyor değil mi? Ancak pek çok API sağlayıcısının yaptığı tam olarak budur, bu nedenle API'lerini kendileri dışında herkese opak bırakır. Rackspace CloudFiles geliştirici ve API kılavuzu böyle bir örnektir; Ne yaptıklarını ve ne sağladıklarını zaten anlamadığınız sürece, yönünüzü bulmak zordur.

Bu nedenle, geliştiriciyi en azından yapmaya çalıştıklarının bir iskeleti ile hızlı bir şekilde çalıştırıp çalıştırmaya yardımcı olan kısa öğreticiler yazın ve ardından genişletebilmeleri için onları daha ayrıntılı, tam olarak belgelenmiş işlevsellik listesine yönlendirin. sahip olduklarına.

Belgelerinizle işiniz bittiğinde, kendiniz dışındaki insanlar için anlamlı olduğunu doğruladığınızdan emin olun. Ağınızdaki diğer geliştiricilere gönderin, onlara belgelere yönlendirmekten başka bir talimat vermeyin ve yaklaşık 15 dakika içinde bir öğreticiyi izlemelerini veya gerçekten temel bir şey oluşturmalarını isteyin. API'nizle 15 dakika içinde temel bir entegrasyona sahip olamazlarsa, yapacak daha çok işiniz var.

Mükemmel ve ayrıntılı belgelerin bazı dikkate değer örnekleri için Twilio, Django ve MailChimp'e bakın. Bu ürünlerin hiçbiri kendi pazarlarında mutlaka en iyisi değildir (hepsi iyi ürünler olsa da), yine de geniş kabul ve pazar paylarını kesinlikle kolaylaştıran pazarlarında en iyi belgelerden bazılarını sağlayarak temaları ayırt ederler.

Kural 2: İstikrar ve Tutarlılık

Facebook'un API'sini daha önce kullandıysanız, API'lerini ne sıklıkta kullanımdan kaldırdıklarını ve tamamen yeniden yazdıklarını bilirsiniz. Onların hacker kültürüne veya ürünlerine ne kadar saygı duyarsanız duyun, onlarınki geliştirici dostu bir bakış açısı değildir. Hala başarılı olmalarının nedeni, API'lerinin harika olması değil, bir milyar kullanıcıya sahip olmalarıdır.

Ancak muhtemelen böyle devasa bir kullanıcı tabanı ve pazar payı lüksüne sahip değilsiniz, bu nedenle çok daha az değişken bir API'ye ihtiyacınız olacak, eski sürümlerin oldukça uzun bir süre çalışır durumda kalmasını ve desteklenmesini sağlayacaksınız. Belki yıllar bile. Bu amaçla, işte bazı ipuçları ve püf noktaları.

Örneğin, API'nize http://myapisite.com/api/widgets URL'si üzerinden erişilebildiğini ve yanıtını JSON biçiminde sağladığını varsayalım. Bu ilk bakışta iyi gibi görünse de, JSON yanıtının biçimini değiştirmeniz gerektiğinde ne olur? Zaten sizinle bütünleşen herkes kırılacak. Hata.

Öyleyse önceden biraz planlama yapın ve API'nizi en baştan, URL'ye açıkça bir sürüm numarası ekleyerek (örneğin, http://myapisite.com/api/widgets?version=1 veya http://myapisite.com/api/widgets/v1 ) sürümlendirin http://myapisite.com/api/widgets/v1 ) ) böylece insanlar sürüm 1'in çalışmasına güvenebilir ve hazır olduklarında sonraki herhangi bir sürüme yükseltebilirler. Bir noktada önceki bir sürümü aşamalı olarak kaldırmanız gerekiyorsa, devam edin, ancak bolca haber verin ve bir tür geçiş planı sunun.

İyi bir URL şeması, URL'de ana sürümleri içerecektir. Çıktı biçiminde veya desteklenen veri türlerinde yapılacak herhangi bir değişiklik, yeni bir ana sürüme geçişle sonuçlanmalıdır. Genel olarak, yaptığınız tek şey çıktınıza anahtarlar veya düğümler eklemekse aynı sürümü tutmak kabul edilebilir, ancak güvenli tarafta olmak için, çıktı her değiştiğinde bir sürümü çarpın.

API'lerin zaman içinde kararlı olmasının yanı sıra dahili olarak tutarlı olması gerekir. Kullanılan uç noktaya bağlı olarak parametre adlarını veya POSTing verilerinin yöntemlerini değiştiren birçok API gördüm. Bunun yerine, API'niz içinde genel olarak ortak parametreleri işlemeli ve API'niz genelinde aynı adlandırma kurallarını ve veri işlemeyi tutarlı bir şekilde yeniden kullanmak için devralma veya paylaşılan bir mimari kullanmalısınız.

Son olarak, kullanıcıların tam olarak nasıl yükseltme yapacaklarını bilmeleri için API'nizin sürümleri arasındaki farklılıkları göstermek için bir değişiklik günlüğü kaydetmeniz ve yayınlamanız gerekir.

Kural 3: Esneklik

Çöp içeri, çöp dışarı (GIGO) çoğu programcı için iyi bilinen bir mantradır. Web API tasarımına uygulandığında, bu yol gösterici ilke, istek doğrulaması için oldukça katı bir yaklaşımı dikte etme eğilimindedir. Kulağa harika geliyor, değil mi? Karışıklık yok, sorun yok.

Yine de her şeyde olduğu gibi, bir denge olması gerekiyor. Kullanıcıların hizmetinizi kullanmak isteyeceği her yolu tahmin etmek mümkün olmadığından ve her istemci platformu tutarlı olmadığından (yani, her platform çok iyi JSON desteğine, iyi bir OAuth kitaplığına sahip değildir, vb.), girdi ve çıktı kısıtlamalarınızla ilgili olarak en azından bir dereceye kadar esnekliğe veya toleransa sahip olun.

Örneğin, birçok API, JSON, YAML, XML vb. gibi çeşitli çıktı biçimlerini destekleyecektir. al., ancak yalnızca biçimin URL'nin kendisinde belirtilmesini destekleyecektir. Esnek kalma ruhuyla, bunun URL'de de belirtilmesine izin verebilirsiniz (örneğin, /api/v1/widgets.json ) veya ayrıca bir Accept: application/json HTTP üstbilgisini okuyup tanıyabilir veya bir ?format=JSON vb. gibi sorgu dizesi değişkeni.

Ve biz hazır buradayken, kullanıcının ?format=json da belirtebilmesi için, belirtilen biçimin büyük/küçük harfe duyarlı olmamasına neden izin vermiyorsunuz? Bu, API'nizin kullanıcısı için gereksiz hayal kırıklığını hafifletmenin klasik bir örneğidir.

Başka bir örnek, değişkenleri girmenin farklı yollarına izin vermektir. Bu nedenle, çeşitli çıktı formatlarınız olduğu gibi, çeşitli girdi formatlarına da izin verin (örneğin, düz POST değişkenleri, JSON, XML, vb.). En azından standart POST değişkenlerini destekliyor olmalısınız ve birçok modern uygulama JSON'u da destekler, bu nedenle bu ikisi başlamak için iyi bir yerdir.

Buradaki nokta, herkesin sizin teknik tercihlerinizi paylaştığını varsaymamanız gerektiğidir. Diğer API'lerin nasıl çalıştığına dair küçük bir araştırma ve diğer geliştiricilerle diyalog yoluyla, faydalı olan diğer değerli alternatifleri toplayabilir ve bunları API'nize dahil edebilirsiniz.

Kural 4: Güvenlik

Güvenlik, web hizmetinizde oluşturulacak en önemli şeylerden biridir, ancak pek çok geliştirici, kullanımı gülünç derecede zorlaştırmaktadır. API sağlayıcısı olarak, API'nize erişirken nasıl kimlik doğrulama ve yetkilendirme yapılacağına ilişkin kullanılabilir örnekler sunmalısınız. Bu, bir son kullanıcının üzerinde saatlerce çalıştığı zor bir konu olmamalıdır. Herhangi bir kod yazmak zorunda kalmamalarını veya yazmalarının 5 dakikadan az sürmesini hedefiniz haline getirin.

Çoğu API için, belirtecin kullanıcıya atanan rastgele bir karma olduğu ve çalınması durumunda herhangi bir noktada sıfırlayabileceği basit bir belirteç tabanlı kimlik doğrulamayı tercih ederim. Belirtecin POST veya bir HTTP üstbilgisi yoluyla geçirilmesine izin verin. Örneğin, kullanıcı bir SHA-1 belirtecini POST değişkeni olarak veya "Yetkilendirme: da39a3ee5e6b4b0d3255bfef95601890afd80709" gibi bir biçimde bir başlık olarak gönderebilir (ve göndermelidir).

Ayrıca, kısa bir sayısal tanımlayıcı değil, güvenli bir belirteç seçin. Geri dönüşü olmayan bir şey en iyisidir. Örneğin, kullanıcı oluşturma sırasında bir SHA belirteci oluşturmak ve onu veritabanında saklamak nispeten basittir. Ardından, bu belirteçle eşleşen herhangi bir kullanıcı için veritabanınızı sorgulayabilirsiniz. Ayrıca, SHA(User.ID + "abcd123") gibi benzersiz bir tanımlayıcı ve bir tuz değeriyle oluşturulmuş bir belirteç yapabilir ve ardından eşleşen herhangi bir kullanıcıyı sorgulayabilirsiniz; örneğin, where TokenFromPost = SHA(User.ID + "abcd123") .

Bir başka çok iyi seçenek de OAuth 2 + SSL'dir. Yine de SSL kullanıyor olmalısınız, ancak OAuth 2'nin sunucu tarafında uygulanması oldukça basittir ve birçok yaygın programlama dili için kitaplıklar mevcuttur.

Yaptığınız API'nin genel bir web sitesinde JavaScript aracılığıyla erişilebilir olması gerekiyorsa, belirteç için hesap başına URL listesini de doğruladığınızdan emin olmanız gerekir. Bu şekilde, hiç kimse API'nize yapılan çağrıları inceleyemez, belirteci kullanıcınızdan çalamaz ve gidip kendileri için kullanamaz.

İşte akılda tutulması gereken diğer bazı önemli şeyler:

• Beyaz listeye alma İşlevselliği. API'ler genellikle veriler üzerinde temel oluşturma, okuma, güncelleme ve silme işlemlerini yapmanıza olanak tanır. Ancak bu işlemlere her varlık için izin vermek istemezsiniz, bu nedenle her birinin izin verilen eylemlerden oluşan bir beyaz listeye sahip olduğundan emin olun. Örneğin, yalnızca yetkili kullanıcıların /user/delete/<id> gibi komutları çalıştırabildiğinden emin olun. Benzer şekilde, kullanıcının isteğinde gönderilen tüm faydalı başlıkların da bir beyaz listeye göre doğrulanması gerekir. İçerik türü üstbilgilere izin veriyorsanız, kullanıcının gönderdiği her şeyin gerçekte desteklenen içerik türlerinin bir while listesiyle eşleştiğini doğrulayın. Olmazsa, 406 Kabul Edilemez yanıtı gibi bir hata mesajı gönderin. Pek çok API otomatik olarak oluşturulduğundan veya bunun yerine bir kara liste kullandığından beyaz liste önemlidir; bu, ne istemediğiniz konusunda açık olmanız gerektiği anlamına gelir. Bununla birlikte, güvenliğin altın kuralı, kesinlikle hiçbir şeyle başlamak ve yalnızca açıkça istediğiniz şeye izin vermektir.

• Kendinizi Siteler Arası İstek Sahteciliğine (CSRF) karşı koruyun. Oturum veya tanımlama bilgisi kimlik doğrulamasına izin veriyorsanız, kendinizi CSRF saldırılarından koruduğunuzdan emin olmanız gerekir. Açık Web Uygulaması Güvenlik Projesi (OWASP), bu güvenlik açıklarını engellemenin yolları hakkında faydalı rehberlik sağlar.

• Kaynaklara erişimi doğrulayın. Her istekte, bir kullanıcının başvurduğu belirli öğeye gerçekten erişmesine izin verildiğini doğrulamanız gerekir. Bu nedenle, bir kullanıcının kredi kartı ayrıntılarını görüntülemek için bir uç noktanız varsa (örneğin, /account/card/view/152423 ), “152423” kimliğinin, kullanıcının gerçekten erişmeye yetkili olduğu bir kaynağa başvurduğundan emin olun.

• Tüm girişi doğrulayın. Bir kullanıcıdan gelen tüm girdilerin, tercihen XML veya JSON gibi karmaşık girdiler kullanıyorsanız, iyi bilinen bir kitaplık kullanılarak güvenli bir şekilde ayrıştırılması gerekir. Kendi ayrıştırıcınızı oluşturmayın, yoksa bir acı dünyasına girersiniz.

Kural 5: Evlat Edinme Kolaylığı

Bu gerçekten gruptaki en önemli kuraldır ve diğerlerinin üzerine kuruludur. Dokümantasyon kuralı sırasında bahsettiğim gibi, bunu API'nizde yeni olan kişilerle deneyin. Birkaç dakika içinde, yalnızca bir öğreticiyi izliyor olsa bile, API'nizin en azından temel bir uygulamasıyla çalışmaya başlayıp başlayabildiklerinden emin olun. Bence 15 dakika iyi bir gol.

API'nizin benimsenmesini kolaylaştırmak ve kolaylaştırmak için bazı özel öneriler şunlardır:

• İnsanların API'nizi gerçekten kullanabileceğinden ve her seferinde ilk seferde çalıştığından emin olun. Yeni kişilerin, bağışıklık kazandığınız bir şekilde kafa karıştırıcı olmadığını doğrulamak için ara sıra API'nizi uygulamaya çalışmasını sağlayın.

• Basit tutun. Süslü bir kimlik doğrulaması yapmayın. Bazı çılgın özel URL şeması yapmayın. SOAP'ı veya JSON'u veya REST'i veya herhangi bir şeyi yeniden icat etmeyin. Geliştiricilerin API + 10 belirsiz yeni teknolojilerinizi değil, yalnızca API'nizi öğrenmesi için halihazırda uygulanmış ve yaygın olarak kabul edilmiş tüm araçları kullanın.

• Hizmetinizle arabirim oluşturmak için dile özgü kitaplıklar sağlayın. Alpaca veya Apache Thrift gibi sizin için otomatik olarak bir kitaplık oluşturmak için bazı güzel araçlar var. Şu anda Alpaca Node, PHP, Python ve Ruby'yi desteklemektedir. Thrift, C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi ve daha fazlasını destekler.

• Gerekli kayıt işlemlerini basitleştirin. Açık kaynaklı bir API geliştirmiyorsanız veya herhangi bir türde kayıt işlemi varsa, kaydolduktan sonra kullanıcının çok hızlı bir şekilde bir eğiticiye yönlendirildiğinden emin olun. Ve sizin tarafınızdan herhangi bir insan etkileşimine ihtiyaç duymadan kayıt işlemini tamamen otomatik hale getirin.

• Mükemmel destek sağlayın. Evlat edinmenin önündeki en büyük engel destek eksikliğidir. Bir hata raporunu nasıl ele alacak ve yanıtlayacaksınız? Peki ya belirsiz belgeler? Deneyimsiz bir kullanıcı mı? Forumlar, hata izleyiciler ve e-posta desteği harika başlangıçlardır, ancak birisi bir hata gönderdiğinde gerçekten onu ele aldığınızdan emin olun. Kimse bir hayalet kasaba forumu veya ele alınmamış dev bir hata listesi görmek istemez.

Web API Özeti

Web hizmetleri ve API'leri boldur. Ne yazık ki, büyük çoğunluğunun kullanımı zordur. Sebepler, kötü tasarımdan, belge eksikliğine, oynaklığa, çözülmemiş hatalara veya bazı durumlarda yukarıdakilerin tümüne kadar uzanır.

Bu gönderideki yönergeleri takip etmek, web API'nizin temiz, iyi belgelenmiş ve kullanımı kolay olmasını sağlamaya yardımcı olacaktır. Bu tür API'ler gerçekten nadirdir ve bu nedenle yaygın olarak benimsenmesi ve kullanılması çok daha olasıdır.