Tek Başına Çalışmaktan Kurtulmak: Postman ile API Geliştirme Konusunda İşbirliği Yapmayı Öğrenmek

API geliştirme, yazılımla ilgili sevdiğim şeylerin büyük bir parçası. İster entegrasyonlar oluşturmak ister ayrıştırılmış web uygulamaları için API'ler hazırlamak olsun, genellikle sadece ben ve koddan ibaretiz.

Çoğu zaman solo API geliştiricisi olarak çalışıyorum. Tek başına ilerlemenin avantajları vardır: hızlı kararlar ve tam kontrol. Ancak her şeyi kafamda tutmak, devretmeyi ve delegasyonu zorlaştırdığı için bu iki ucu keskin bir kılıç. Tek başıma ilerlemek, üzerinde çalışabileceğim projelerin boyutunu ve karmaşıklığını sınırlıyor. Sonuçta ben sadece bir kişiyim.

Postacı, istek gönderme, ortamları yönetme ve testleri çalıştırma gibi API çalışmaları için birincil aracımdır. Solo iş akışıma aşinayım. Ama merak etmeye başladım: Bir ekip ortamında Postman daha fazla ne sunabilir? İşbirliğini nasıl geliştirebilir ve geliştirme sürecini nasıl kolaylaştırabilir?

Bu soruları araştırmak için "X Nihilo" adını verdiğim örnek bir API üzerinde çalışmaya başladım.

Örnek API: X Nihilo

X Nihilo, sakladığınız veya gönderdiğiniz parametrelere göre 280 karakterlik tweetler oluşturmanıza yardımcı olur. Bir konu, bir hedef, alınacak üslubun bir açıklamasını ve hedef kitlenin bir açıklamasını sağlarsınız. Perde arkasında API, OpenAI'nin API'sine metin tamamlama için bir istek gönderecek ve bu, tweet'in oluşturulmasına yardımcı olacak.

Ayrıca ton ve hedef kitle için kullandığınız dizeleri kaydedip daha sonraki tweet isteklerinizde yeniden kullanabilirsiniz.

Temel API geliştirme iş akışımı gözden geçirelim.

Tek başıma ilerlemek: solo iş akışım

İş akışımdaki ilk adım, API'yi tasarlamak ve bir OpenAPI spesifikasyonu yazmaktır. Postman'da yeni bir API oluşturdum ve ardından yeni bir API tanımı başlattım.

Biraz düşündükten sonra (ve açıklamalarıma dayanarak ilk OpenAPI spesifikasyonunu oluşturmak için harika olan ChatGPT ile doğrudan çalıştıktan sonra), spesifikasyonumu yazdırdım:

OpenAPI spesifikasyonum hazır olduğunda bir yol ayrımına geldim. Bu API ile etkileşime girmenin nasıl görüneceğini göstermek için bir sahte sunucu ve bazı örnek istekler ve yanıtlar kurmalı mıyım? Yoksa uygulama kodunu yazmaya başlamalı mıyım?

Solo bir geliştirici olarak herhangi bir zamanda yalnızca API üreticisi veya API tüketicisi olabilirim. Ben de karar verdim: taklit yapmaya gerek yok; içimdeki tüketicinin beklemesi gerekecek. Hadi biraz kod yazalım!

Birkaç dakika sonra…

Node.js'yi Express ile kullanarak ve PostgreSQL veritabanıyla konuşarak temel API'mi uyguladım. İşte oluşturmam gereken her şeyin özeti:

• POST /signin bir username ve password alır, veritabanındaki kayıtlara göre kimlik doğrulaması yapar ve ardından sonraki tüm isteklerde kullanılabilecek imzalı bir JWT döndürür.
• POST /generateTweet 280 karakterlik (maks.) bir tweet oluşturur. Bir topic (dize) ve bir goal (dize) alır. Aynı zamanda bir tone (string) veya bir toneId (depolanan tonun tam sayı ID'si) ile birlikte bir audience (string) veya bir audienceId (depolanan hedef kitlenin tam sayı ID'si) alır. tone ve/veya audience kitle dizeleri sağlandığında API bunları veritabanına kaydeder.
• GET /tones kimliklerinin ve karşılık gelen dizelerin bir listesini döndürür. GET /audiences yeniden kullanılabilir hedef kitle dizeleri için aynısını yapar.
• DELETE /tones bir ton kimliği alır ve o ton kaydını siler. DELETE /audiences hedef kitle kayıtları için aynı işlemi yapar.

İlk uygulama tamamlandıktan sonra sıra Postman'a dönüp bazı istekleri çalıştırmaya başlamanın zamanı gelmişti.

Değişkenlerin olduğu bir ortam yaratın.

Öncelikle “Test” adında yeni bir ortam oluşturdum. Geçerli bir username ve password birlikte root_url adresimi saklamak için değişkenler ekledim.

Koleksiyon ve istek oluşturma

Daha sonra yeni bir koleksiyon oluşturdum ve ilk isteğimi ekledim: kimlik doğrulamayı denemek için /signin bir POST isteği.

API sunucum bir terminal penceresinde çalışırken ilk isteğimi gönderdim.

Başarı! Gelecekteki isteklerimde ihtiyaç duyacağım jetonumu aldım.

Bu sefer bir tweet oluşturmak için yeni bir istek oluşturdum.

Yetkilendirmeyi "Taşıyıcı Token" kullanacak şekilde ayarladığımdan emin oldum ve önceki istekte az önce aldığım jetonu sağladım.

İşte yanıt:

İşe yarıyor!

Solo yaklaşımı özetlemek

Bu benim solo iş akışıma basit bir bakış. Tabii ki, yol boyunca birkaç şey daha yapardım:

• Bir /signin isteği gerçekleştirmek için bir ön istek betiği yazın ve ardından yanıttaki belirteci temel alarak bir ortam değişkeni ayarlayın.
• OpenAPI spesifikasyonundaki diğer tüm uç noktalar için istekler oluşturun.
• Uç durumlarımı kapsadığından emin olarak her uç nokta için testler yazın.

Tek başıma çalışıyorsam bu temel iş akışı beni bitiş çizgisine oldukça yaklaştırıyor. Bu sorun olmasa da, muhtemelen Postman'daki mevcut özelliklerin yalnızca yüzeyini çizdiğimi biliyorum . Ve eğer bir takımda çalışıyor olsaydım Postman'dan çok daha fazlasına ihtiyacım olacağını biliyorum.

Aha anı: Neden Postman'ı takımlar için düşünmelisiniz?

Ya artık X Nihilo için tek başına API geliştiricisi olamazsam? Bu, birkaç nedenden dolayı gerçekleşebilir:

• X Nihilo'nun boyutu ve karmaşıklığı artıyor ve artık tek bir API geliştiricisi onu desteklemek için yeterli değil.
• X Nihilo, birden fazla API geliştiricisini ve hatta birden fazla API ekibini içeren daha büyük bir API projesinin yalnızca küçük bir parçasıdır.

Müşterilere yönelik API projelerimin tümü kendi başıma oluşturabileceğim küçük projeler olmayacak. Bazen API oluşturan bir ekibin parçası olmam gerekecek. API ekibine liderlik etmem bile gerekebilir.

Böyle bir durumda, Postman'de solo zihniyetimi geride bırakmam ve işleri tek başıma yapma tarzımı bırakmam gerekecek. Bu beni Postman'ın takımla ilgili özelliklerini incelemeye motive etti.

Postman'ın ekibinin (kurumsal) özelliklerini keşfetme

Postman'ın ücretsiz bir katmanı vardır ve bazı sınırlı işbirliği özellikleri sunar; küçük bir ekipseniz (yani üçten fazla geliştirici değilseniz) bu yeterli olabilir. Postman, Enterprise Essentials katmanının bir parçası olarak ek özelliklere sahiptir. Bunlar, Postman'ı geniş çapta kullanan daha büyük kuruluşlardaki API ekipleri için mükemmeldir.

Çalışma alanı paylaşımı

Bir çalışma alanı, ekiplerinizin birden fazla API projesinde işbirliği yapmasına olanak tanır. Farklı API'ler üzerinde çalışan farklı ekipleriniz varsa ancak bu API'ler birbirleriyle etkileşime giriyorsa bu harika bir şeydir (bu genellikle daha büyük yazılım kuruluşlarında görülen durumdur).

Çalışma alanları, gerçek zamanlı işbirliğini sağlamak için mükemmeldir. Ekip üyeleri API belgelerini düzenleyebilir, istek oluşturma veya testler yazma üzerinde birlikte çalışabilir ve tüm ekibin kullanabileceği bir örnek sunucu oluşturabilir. Düzenlemeler yapıldıkça tüm ekiple gerçek zamanlı olarak senkronize edilirler.

Sürüm kontrolü

Tek başına bir API geliştiricisi olarak kodumun sürüm kontrolünü önemserken, Postman koleksiyonlarımın veya ortamlarımın sürüm kontrolünü pek umursamadım. Bir şeyi değiştirirsem (bir isteği değiştirirsem, bir testi güncellersem, bir ortam değişkenini kaldırırsam), etkilenen tek kişi benim. Önemli değil.

Bir takımda çalıştığınızda, işlerin ne zaman değişeceğini kesinlikle bilmek istersiniz. Bazen değişiklikleri geri almanız gerekir. Neyse ki Postman Enterprise'ı kullanan ekipler için Postman , koleksiyonlar, çalışma alanları ve API'ler için bir değişiklik günlüğüne erişmenizi sağlar. Koleksiyonları zamanın daha önceki noktalarına geri alabilirsiniz. Bir ekipteki API geliştiricisi olarak buna ihtiyacınız olacak. Çoğu zaman bunun nedeni Bob'un koleksiyonu berbat etmesidir. Bazen sen Bob'sun.

Rol tabanlı erişim ve kullanıcı organizasyonu

Postacı çalışma alanındaki herkesin aynı düzeyde izinlere sahip olması gerekmez. Bazı ekip üyeleri test uzmanıdır ve yalnızca istek gönderme ve testleri çalıştırma becerisine ihtiyaç duyarlar, ancak bunları değiştirmeye değil. Diğerleri yalnızca API tanımlarını değiştirmesine izin verilen tasarımcılar olabilir.

Postman'da ekip üyelerine roller atayabilirsiniz. Bu, her ekip üyesinin bir ekip veya çalışma alanı içinde sahip olduğu erişim türünü ve izin düzeyini etkiler.

Ekipler ayrıca, ekip dışındaki kişilerin erişimini kısıtlayan özel çalışma alanlarına da sahip olabilir.

Ayrıca Postman Enterprise'ın "etki alanı yakalamayı" desteklediğini fark ettim. Bu, temel olarak, (örneğin) mycompany.biz alan adından herkese erişim vererek kuruluşunuzdaki tüm kullanıcıları ayarlayabileceğiniz anlamına gelir.

Satır içi yorumlar ve tartışmalar

Postman'ın yalnızca Enterprise Essentials'da değil, tüm planlarında bulunan bir işbirliği özelliği vardır. Bu, ekip üyelerinin koleksiyonlara (klasörler, istekler, örnekler veya çekme istekleri üzerine) yorum ekleme yeteneğidir. Doğrudan Postman'da yorum yapabilmek ve tartışabilmek, ekip API gelişimi için çok önemlidir. Ekibinizin API geliştirme çalışmalarının çoğu Postman'da gerçekleşeceğinden, tartışmanızın orada (GitHub veya başka bir harici hizmet yerine) yapılması mantıklı olacaktır.

Ekip API'si geliştirme: Kazanmak için Postacı

Ne zaman bir takıma katılsam, kullanmayı sevdiğim araçları yanımda getiriyorum ama onları takım arkadaşlarıma pek zorlamıyorum. Kendi araçlarının olduğunu düşünüyorum. Yani her biri kendine ait. Ancak çoğu API geliştiricisinin alet kemerinde Postacı'nın bulunduğunu hissediyorum. Bir ekipteki birkaç API geliştiricisinin hepsinin Postman'ı bireysel olarak, tek başına bir zihniyetle ve bu ekip özelliklerinden bazılarından yararlanmadan kullanması çok yazık olurdu. Postman Enterprise'ın özelliklerinden yararlansalardı, şunları elde edeceklerdi:

Verimliliği arttırmak

Paylaşılan bir çalışma alanında paylaşılan API tanımıyla başlarsınız. Bir ekip üyesi tanımı (veya belgeleri, testleri veya ortamları) düzenlediğinde, düzenlemeler senkronize edilir ve herkes en yeni ve en iyiye sahip olur.

Bir koleksiyondaki herkes aynı istek kümesi üzerinde çalışır ve herkes kullanılacak tüm testlere erişebilir. Tüm bu kolaylıklar ekibin verimliliğini artıracak ve bu da onların gelişim hızını hızla artıracaktır.

Daha az yanlış anlama

Herkes aynı gerçek kaynağından (çalışma alanınız) çalıştığında ve geliştirme için kullandıkları araç içerisinde yorum yapabildiklerinde ve sohbet edebildiklerinde, bu daha az yanlış anlamalara yol açacaktır. Ekibiniz, uç noktanın sorgu parametrelerini mi yoksa yol parametrelerini mi alması gerektiği konusunda kafa karışıklığı nedeniyle zaman kaybetmeyecektir. Her şey netleşecek.

Anahtar paket servisi

Postman'ın ekipler ve şirketler için olduğunu bilmiyordum. Artık bildiğime göre, benim büyük çıkarımlarım şu: Takım oyuncuları takım için iyi olan araçları kullanır.

Yalnız bir API geliştiricisi olduğumda Postman benim için harika oldu. Neyse ki, bir API geliştirme ekibindeyken benim için harika olacak özelliklere de sahip. Benim için bu, koleksiyonlar, değişiklik günlükleri ve sürüm kontrolü içindeki düzenlemelerin ve erişim için ayrıntılı izinlerin gerçek zamanlı senkronizasyonudur. Artık daha büyük ekiplerle daha büyük API projeleri üstleneceğim için heyecanlıyım.

Mutlu kodlama!

Burada da yayınlandı.