Sofa - REST'e gitmenin en iyi yolu (GraphQL)

REST vs GraphQL tartışmalarını bir kez ve herkes için sonlandırmak

Bir çırpıda REST API'sini etkinleştir

TL; DR

  • REST ve GraphQL arasında seçim yapma - GraphQL uygulamanızdan otomatik olarak tamamen RESTful bir API oluşturun (bir kütüphane ve tek bir kod satırıyla)
  • REST'i kullanırken ve açığa çıkarırken arkadaki ve öndeki GraphQL özelliklerinden en iyi şekilde yararlanın
  • GraphQL ile arka uç yığınınızı geliştirirken mevcut tüm müşterilerinizi REST ile destekleyin
  • Sadece bir rota adlandırarak ve bir sorgu ekleyerek, ön uçlarınız için müşteriye göre özel olarak ayarlanmış özel REST bitiş noktaları oluşturun
  • GraphQL vs REST hakkında tartışmayı durdur. GraphQL kullanın, REST oluşturun ve her ikisinden de en iyisini alın
  • Diğer taraftan (REST to GraphQL) her iki dünyanın en iyisini elde edemezsiniz, ancak daha az güçlüdür, sunucu uygulamasını GraphQL'in bazı avantajlarıyla sürdürmek daha zordur. Yine de göç için iyi ve hızlı bir başlangıç.

Bir dakika ne!?

GraphQL ve REST API'lerinin avantajları ve dezavantajları ve hangisinin kullanılacağına nasıl karar verileceği hakkında birçok makale yazılmıştır. Bunları burada tekrarlamayacağım.

Akıllı danışmanların bu makaleleri yazmak, bu makaleleri okumak için harcadıkları çok fazla zaman ve enerji varken, çoğu, bu kullanım durumlarını belirtmeden “kullanım durumunuza bağlıdır” özeti ile bitmiştir!

Uzun yıllardır REST, GraphQL ve SOAP API'leri ile çalışıyorum. Bu yüzden neden bu kullanım durumlarının bir listesini ve neden her birini kontrol edemediğimizi düşündüm - GraphQL'de REST ile yapamayacağınızı ve GraphQL ile yapmak istemediklerinizi REST'i tercih edersiniz.

Bu listeyi oluşturduktan sonra aniden düşündüm - ya başka bir seçenek olsaydı - ya da güçlü GraphQL sunucum benim için sadece bir REST API oluşturabilseydi?

O zaman iki dünyanın da en iyisini elde edebilirim!

Fikir ve uygulamalara ne kadar çok daldıysam o zaman daha çok fark ettim ki bu sadece bizim için yarattığımız her iki API türüne sahip olabileceğimiz değil, sadece REST API'lerini ortaya çıkarmak istiyorsak bile, ve müşterilerimizin hiçbiri GraphQL kullanmıyor, GraphQL REST API'leri yaratmanın en iyi yolu!

Yukarıdaki cümle nasıl bir anlam ifade ediyor ?!

Genellikle biz (Lonca) şirketlere ve kuruluşlara API'lerini modernize etme konusunda yardım ettiğimizde, GraphQL'in faydalarını ilk anlayanlar, açık nedenlerden ötürü öncül geliştiricilerdir. Ancak, arka uç geliştiricileri “Get it” yaptıkları anda, teknolojinin en büyük savunucuları haline gelirler. Ancak hala mevcut müşterileri ve 3. parti ortakları desteklemeleri gerekiyor.

Bu nedenle, yeni oluşturulan REST API'lerinin, arka uç geliştiricilerini mutlu eden dahili GraphQL uygulamasından çok sayıda özellik ve yararı var:

  • Her zaman güncel olan tamamen üretilmiş belgeler (Swagger, OpenAPI ve GraphiQL)
  • Kutunun dışında gerçekten RESTful API
  • Webhooks olarak GraphQL Abonelikleri
  • Verilerin çalışma zamanı doğrulaması - alınan verilerin şema ve sorgunun yapısıyla eşleştiğinden% 100 emin olun. Tam olarak göndermek istediklerimi gönderiyorsunuz, dize bir dizedir, bir nesne tam olarak aynı özelliklere sahiptir.
  • Özel bir bitiş noktası oluşturmak artık bir rota adı seçmek ve ona bir sorgu eklemekle ilgili. yapılır. Müşteriye özel uç noktaların oluşturulması ve sürdürülmesine artık elle çalışmanıza gerek yok!
  • GraphQL’in gelişen API’lerin felsefesini şemalar yoluyla kullanın - artık acı verici V1 - V2 API geçişleri.
  • İnsanları işe almak için daha kolay olan modern teknolojiyi kullanın. Facebook, Airbnb ve diğerleri gibi şirketler GraphQL'e taşındı. Hiçbiri geri dönmedi.
  • GraphQL'in gücü, MVC'den manuel olarak yazılmış kontrolörler yerine API uygulamanızı oluşturmaya karar verir.

Çözücüleri olanlardan ne alırım?

  • Verileri dönüştürmek daha kolaydır, böylece yanıtla eşleşir (GraphQL Schema). Bunun nedeni, her işletmenin kendi çözümleyicisine sahip olmasıdır, bu nedenle haritalama daha küçük parçalara taşınır ve tüm uygulama boyunca yeniden kullanılır.
  • GraphQL, her çözümleyicide kolayca veri paylaşmanıza izin verir, buna İçerik diyoruz.
  • Verileri, bir API oluşturmaya gerçekten yardımcı olan fikirli bir şekilde tanımlamanıza ve çözmenize zorlar. Paralel olarak işlevler çalıştırır (aynı düzeyde iç içe geçmiş işlevler), zaman uyumsuzluklarla ilgilenir ve sonunda bunların hepsini tek bir nesnede birleştirmekten sorumludur, bu nedenle düşünmeniz gerekmez.

Sofa - RESTful API'ler oluşturmak için GraphQL kullanın

Böylece, tamamen RESTful ve yapılandırılabilir bir API ağ geçidi oluşturmak için GraphQL sunucunuza kurduğunuz açık kaynaklı bir kütüphane olan Sofa'yı (amaçlanan) oluşturduk. REST için GraphQL kullanın.

“Nasıl yapılır” dersi

RESTful bir API oluşturmaya ilişkin adım adım öğreticiyi kısa bir adım oluşturalım.

Adım 1: npm `sofa-api` paketini kurun ve aşağıdaki kod satırını ekleyin:

Adım 2: Kanepede REST'e gidin, işiniz bitti.

Kamil Kisiela, Sofa'yı Carlos Rufo'nun SpaceX GraphQL API uygulamasına tek bir taahhütte ekledi.

Tamamen oluşturulmuş REST uç noktalarına, Swagger canlı belgelerine, GraphiQL editörüne ve GraphiQL-Explorer'a göz atın!

Bu arada, burada gördüğünüz şey, başka bir REST API'sinin üstünde oluşturulan bir GraphQL API'sinin tepesinde oluşturulan bir REST API'sı….

Bunu neden yaptın?

Eski REST uygulamalarından yavaş yavaş geçiş

Bu aslında gitmek için iyi bir yön. Çalıştığımız birçok şirkette, eski web servislerini kullanan eski teknolojiyi kullanarak REST API katmanları oluşturdular.

Ancak bu REST uygulamaları sorunlu (insanların GraphQL'e geçmeyi seçtiği tüm nedenlerden dolayı) sorunlu.

Dolayısıyla, bizim yolumuz bu REST katmanlarının üstüne GraphQL uygulamaları oluşturmak, müşterileri bu uygulamalara geçirmek ve ardından eski RESTful katmanını kademeli olarak kaldırmak ve hizmetleri doğrudan çağırmaktır.

Sofa kullanımı bu geçişleri çok daha hızlı bir hale getirdi, çünkü mevcut tüm istemcilere GraphQL uygulamalarımıza geçiş yapmalarını sunabiliyoruz. Aynı REST uç noktalarını GraphQL'in üzerine gösteriyoruz ve tüm isteklerimize ve özel REST uç noktalarını orijinal, eski REST uygulamalarından çok daha hızlı bir şekilde karşılayabildiğimiz için katmanımıza mutlu bir şekilde hareket ediyorlar.

Bana daha fazla ayrıntı ver

Kanepe varsayılan olarak Ekspresi kullanır ancak başka herhangi bir sunucu çerçevesini kullanabilirsiniz. Kanepe aynı zamanda agnostik GraphQL sunucu uygulamasıdır.

Belgelendirme için Sofa web sitesine ve sorunları bildirmek ve yardım etmek için Github deposuna gidin.

Sofa nasıl çalışır?

Kaputun altında, Sofa her Sorgu ve Mutasyon tipi alanını rotalara dönüştürür. İlk rota grubu sadece GET metodu ile kullanılabilir, diğer yandan mutasyonlar POST alır.

Sofa, tüm olası değişkenlerle (derinlemesine yuvalanmış olanlar dahil) bir işlem oluşturmak için GraphQL’in AST'sini kullanır ve tam olarak ne getireceğini bilir. Daha sonra isteğin gövdesini operasyonun değişkenlerine dönüştürür ve bunu Şemaya karşı yürütür. Yerel olarak gerçekleşir, ancak harici bir GraphQL Server veya hatta Apollo Link kullanmak da mümkündür.

Şu anda Sofa, Express için yerleşik bir desteğe sahip ancak farklı bir çerçeve kullanmak tamamen mümkün. Ana konsept tamamen aynı kalır, bu nedenle sadece isteği işleme biçimimiz farklı sunucu uygulamalarına göre değişir.

Webhooks olarak GraphQL Abonelikleri?

İşe yaraması basit bir şekilde, özel bir rota arayarak bir abonelik başlatıyorsunuz ve daha sonra aboneliği güncellemek ve hatta durdurmak için kullanılabilecek benzersiz bir kimliğe sahip oluyorsunuz. Abonelikler Webhooks'tur. Sofa, API'nizde ne zaman bir olay yaşandığını tam olarak bilir ve abone olduğunuz son noktadan sizi bilgilendirir.

Modeller / Kaynaklar

Bazı durumlarda, bütün bir nesneyi göstermek istemezsiniz, sadece kimliğini gösterirsiniz. Bunu Sofa ile nasıl yapabildin? İki sorguya ihtiyacınız var. Birincisi, sadece kimliğine dayanarak tek bir varlık döndürmek zorundadır (ki bu argüman olacaktır) ve ikincisi bunların bir listesini çözmelidir. Ayrıca adlar eşleşmelidir; örneğin, Kullanıcı adı verilen bir kaynağın iki sorgusu olmalıdır: user (id: ID): User ve users: [User]. Neredeyse REST ile yapacağınız aynı şey.

Sorgu yazın
  user (id: ID!): Kullanıcı
  kullanıcılar: [Kullanıcı]
}

Sofa rotaları oluşturmadan önce, bu Modelleri arar ve onları kaydeder, böylece işlemler oluşturulduğunda her şeyi almazsınız, sadece bir kimlik alırsınız.

Peki ya bütün nesneyi sadece birkaç yerden almak istersen?

Bunu yapmanıza izin veren ignore adında bir seçenek var. Varsayılan davranışın üzerine yazmak istediğiniz yolu kolayca geçebilirsiniz.

Aşağıdaki şemaya bakıldığında, sadece yazarın kimliğini alırsınız.

Kitap Türü {
  yaptım
  title: Dize!
  Yazar: Kullanıcı!
}
Sorgu türünü genişlet
  kitap (kimlik: ID!): Kitap
  kitaplar: [Kitap]
}

İgnore ile: ['Book.author'], tüm bir User nesnesi ile sonuçlanır.

kanepe({
  ...,
  yoksay: ['Book.author'],
})

Swagger ve OpenAPI

GraphQL’in tür sistemi sayesinde Sofa, REST API’niz için her zaman güncel belgeler oluşturabilir. Şu anda Swagger ve OpenAPI teknik özelliklerini destekliyoruz, ancak farklı özellikleri kabul etmek gerçekten kolay.

özet

sofa-api, tüm gücünü kullanarak bir GraphQL sunucusundan en iyi REST uygulamalarını içeren bir RESTful API oluşturmayı son derece kolaylaştırır.

REST vs GraphQL hakkında tartışarak hayatınızı boşa harcamayın - Üretken olun, her iki dünyanın da avantajlarından yararlanın ve API geliştirmenin geleceğine geçin.

Umarım bu, orada son REST vs. GraphQL makalesi olur ... Bunu yapmayacağını düşünüyorsanız, bir kullanım çantası ile yorum yapın ve deneyelim!

Bu konuda benimle çalıştığı ve bu kütüphaneyi gerçeğe dönüştürdüğü için Kamil Kisiela'ya teşekkürler!

Bizi GitHub ve Medium'da takip edin, önümüzdeki birkaç hafta içinde GraphQL'i kullanarak son yıllarda öğrendiklerimiz hakkında daha birçok yayın yayınlamayı planlıyoruz.