Sorgu dizesi ile URI tarafından bir REST api tasarlama

Diyelim ki bununla ilişkili üç kaynağım var:

Grandparent (collection) -> Parent (collection) -> and Child (collection)

Yukarıdakiler, bu kaynaklar arasındaki ilişkiyi şöyle gösterir: Her büyükbaba veya büyükanne bir veya birkaç ebeveyne eşlenebilir. Her ebeveyn bir veya birkaç çocuğa harita verebilir. Çocuk kaynağına karşı arama yapmayı ancak filtre kriterleri ile desteklemeyi istiyorum:

Müvekkillerim bana büyükbaba veya büyükanne için bir kimlik referansı verirse, sadece o büyük ebeveynin doğrudan soyundan gelen çocuklara bakmak istiyorum.

Müvekkillerim bana bir ebeveyne bir kimlik referansı gönderirse, sadece ebeveyimin doğrudan torunları olan çocukları araştırmak istiyorum.

Ben böyle bir şey düşündüm:

GET /myservice/api/v1/grandparents/{grandparentID}/parents/children?search={text}

ve

GET /myservice/api/v1/parents/{parentID}/children?search={text}

Yukarıdaki şartlar için sırasıyla.

Ama aynı zamanda böyle bir şey yapabilirim:

GET /myservice/api/v1/children?search={text}&grandparentID={id}&parentID=${id}

Bu tasarımda, müşterimin bana bir ya da diğerini sorgu dizgisinde geçirmesine izin verebilirim: ya grandparentID ya da parentID, ama ikisi de değil.

Benim sorularım:

1) Hangi API tasarımı daha RESTful ve neden? Anlamsal olarak, aynı anlama gelir ve aynı şekilde davranırlar. URI'deki son kaynak, "çocuklar" dır ve etkin olarak müşterinin çocuk kaynakları üzerinde çalıştığını ima eder.

2) Müşterinin bakış açısından anlaşılabilirliği ve tasarımcının bakış açısıyla bakımı açısından her birinin lehte ve aleyhinde olanlar nelerdir?

3) Kaynağınızdaki "filtrelemenin" yanı sıra gerçekten kullanılan sorgu dizeleri nelerdir? İlk yaklaşıma girerseniz, filter parametresi URI'da sorgu dizesi parametresi yerine path parametresi olarak gömülür.

Teşekkürler!

İlk

Başına gibi RFC 3986 §3.4 (Tekdüzen Kaynak Tanımlayıcıları § (sözdizimi Bileşenleri) | Sorgu

3.4 Sorgu

Sorgu bileşeni, yol bileşenindeki verilerle (Bölüm 3.3), URI'nin şeması ve adlandırma yetkisi (varsa) kapsamında bir kaynağı tanımlamaya hizmet eden hiyerarşik olmayan veriler içerir.

Sorgu bileşenleri, hiyerarşik olmayan verilerin alınması içindir; doğada soy ağacından daha hiyerarşik olan çok az şey var! Ergo - “REST-y” olup olmadığını düşünmeden bağımsız olarak - İnternet üzerindeki sistemlerin formatları, protokolleri ve çerçevelerine uymak için ve geliştirmek için sorgu dizesini kullanmamalısınız.

REST'in bu tanımla ilgisi yoktur.

Özel sorularınızı belirtmeden önce, "search" sorgusu parametreniz kötü adlandırılır. Sorgu segmentinize bir anahtar / değer çiftleri sözlüğü gibi davranmak daha iyi olur.

Sorgu dizeniz daha uygun olarak tanımlanabilir

?first_name={firstName}&last_name={lastName}&birth_date={birthDate} vb.

Özel sorularınızı cevaplamak için

1) Hangi API tasarımı daha RESTful ve neden? Anlamsal olarak, aynı anlama gelir ve aynı şekilde davranırlar. URI'deki son kaynak, "çocuklar" dır ve etkin olarak müşterinin çocuk kaynakları üzerinde çalıştığını ima eder.

Bunun, inandığın kadar açık bir kesim olduğunu sanmıyorum.

Bu kaynak arabirimlerinin hiçbiri RESTful değildir. Majör RESTful mimari tarzı ön koşulu Application State geçişler hypermedia olarak sunucudan iletilmelidir gerektiğidir. İnsanlar URI'lerin yapısını üzerinde bir şekilde "RESTful URI'lar" yapmak için çalıştılar, ancak REST ile ilgili resmi literatürde bu konuda söylenecek çok az şey var. Benim kişisel görüşüm, REST hakkındaki meta-yanlış bilginin çoğunun eski ve kötü alışkanlıkların kırılması amacıyla yayınlandığı yönünde. (Gerçekten "RESTful" bir sistem oluşturmak aslında oldukça fazla bir iştir. Endüstri, "REST" e başvurdu ve bazı ortogonal kaygıları saçma nitelikler ve kısıtlamalar ile geri doldurdu.)

REST literatürünün söylediği şey, HTTP'yi uygulama protokolünüz olarak kullanacaksanız, protokolün şartnamelerinin resmi gerekliliklerine uymanız ve "giderken http yapamazsınız ve hala http kullandığınızı beyan edemezsiniz" dır. ; Kaynaklarınızı tanımlamak için URI'leri kullanacaksanız, URI / URL'lerle ilgili şartnamelerin resmi şartlarına uymalısınız.

Sorunuz doğrudan yukarıda bağlantı kurduğum RFC3986 §3.4'te ele alınmaktadır. Bu konudaki sonuç, uygun bir URI'nin bir API'yi "RESTful" olarak değerlendirmek için yetersiz olmasına rağmen, sisteminizin gerçekte "RESTful" olmasını istiyorsanız ve HTTP ve URI'leri kullanıyorsanız, bu durumda hiyerarşik verileri tanımlayamazsınız. sorgu dizesi çünkü:

3.4 Sorgu

Sorgu bileşeni hiyerarşik olmayan veriler içeriyor

...bu kadar basit.

2) Müşterinin bakış açısından anlaşılabilirliği ve tasarımcının bakış açısıyla bakımı açısından her birinin lehte ve aleyhinde olanlar nelerdir?

İlk ikisinin "artıları" , doğru yolda olmalarıdır . Üçüncü olanın "eksileri" yanlış anlaşılıyor gibi görünüyor.

Anlaşılabilirliğiniz ve bakımınızla ilgili endişeleriniz söz konusu olduğunda, bunlar kesinlikle özneldir ve müşteri geliştiricisinin anlama düzeyine ve tasarımcının tasarım parçalarına bağlıdır. URI belirtimi, URI'lerin nasıl biçimlendirileceği konusundaki kesin cevaptır. Hiyerarşik verilerin yol üzerinde ve yol parametreleriyle temsil edilmesi gerekiyor. Hiyerarşik olmayan verilerin sorguda gösterilmesi gerekiyordu. Parça daha karmaşık, çünkü onun anlambilimi, özellikle talep edilen temsilin medya türüne bağlı. Bu nedenle, sorunuzun "anlaşılabilirliği" bileşenine değinmek için, ilk iki URI'nin gerçekte söylediklerini tam olarak çevirmeye çalışacağım. Ardından, geçerli URI'lerle yapmaya çalıştığınız şeyleri temsil etmeye çalışacağım.

Sözlü URI'larınızın semantik anlamlarına çevirisi /myservice/api/v1/grandparents/{grandparentID}/parents/children?search={text} Bu, büyükanne ve büyükbabaların ebeveynleri için, çocuklarının URI'nızla söylediklerinizi yalnızca bir büyük ebeveynin search={text} kardeşlerini ararken tutarlı olduğu anlamına gelir. "Büyükanne ve büyükbaba, ebeveynler, çocuklar" ile, bir "büyükbaba veya büyükbaba" bulduktan sonra ebeveynlerine bir kuşak yükseldi ve sonra ebeveynlerin çocuklarına bakarak "büyükbaba" nesline geri döndüm.

/myservice/api/v1/parents/{parentID}/children?search={text} Bu, {parentID} tarafından tanımlanan ebeveyne göre, çocuklarının ?search={text}neyi istediğinizi düzeltmek için daha yakın olduğunu ve sizin tüm API'nizi modellemek için kullanılabilecek bir ebeveyn > çocuk ilişkisini temsil ettiğini söyler. Bu şekilde modellemek için yük, müşteriye "büyük ebeveyn" varsa, sahip oldukları kimlik ile aile grafiğinin görmek istedikleri kısmı arasında bir dolaylı katmanın olduğunu kabul etmek için yüklenir. "GrandparentId" adlı bir "çocuk" bulmak için, /parents/{parentID}/childrenhizmetinizi arayabilir ve sonra geri gönderilen her çocuğu arayabilirsiniz, çocuklarını kişi tanımlayıcınız için arayabilir.

Gereksinimlerinizin URI'ler olarak uygulanması Ağaçta yürüyebilecek daha genişletilebilir bir kaynak tanımlayıcıyı modellemek istiyorsanız, bunu başarabileceğiniz birkaç yol düşünebilirim.

1) İlki, zaten itiraz ettim. Kompozit bir yapı olarak "İnsanlar" grafiğini temsil eder. Her insan, Üstler Arası yolu üzerindeki üstündeki nesile ve Altındaki yolu Alemi yoluyla kendi altına göndermiştir.

/Persons/Joe/Parents/Mother/Parents Joe'nun anneannesinin dedesini almanın bir yolu olurdu.

/Persons/Joe/Parents/Parents Joe'nun büyükanne ve büyükbabasını almanın bir yolu olurdu.

/Persons/Joe/Parents/Parents?id={Joe.GrandparentID} Elinizde olan tanımlayıcıya sahip Joe'nun büyük ebeveynini yakalardı.

ve bunların hepsi bir anlam ifade eder (“Ebeveynler / Ebeveynler / Ebeveynler” modelindeki şube kimliği eksikliği nedeniyle sunucuda bir dfs zorlayarak göreve bağlı olarak burada bir performans cezası olabileceğini unutmayın.) Ayrıca, İstediğiniz sayıda nesli destekleme yeteneği. Herhangi bir sebepten ötürü, 8 nesile bakmak istersen, bunu şu şekilde temsil edebilirsin:

/Persons/Joe/Parents/Parents/Parents/Parents/Parents/Parents/Parents/Parents?id={Joe.NotableAncestor}

ancak bu, bu verileri temsil etmek için ikinci baskın seçeneğe yol açar: bir yol parametresiyle.

2) "hiyerarşi sorgulamak" giden yolun parametreleri kullanın Sen tüketiciler üzerindeki yükü hafifletmek ve hala mantıklı bir API var yardımcı olmak için aşağıdaki yapıyı geliştirebilir.

147 nesiller geriye bakmak için, bu kaynak tanımlayıcıyı yol parametreleriyle temsil etmenizi sağlar

/Persons/Joe/Parents;generations=147?id={Joe.NotableAncestor}

Joe’yu Büyük Anne ve Büyükbabası’ndan bulmak için, grafikte Joe’nun kimliği için bilinen sayıda nesiller görebilirsiniz. /Persons/JoesGreatGrandparent/Children;generations=3?id={Joe.Id}

Bu yaklaşımlarda dikkat edilmesi gereken en önemli şey, tanımlayıcı ve istekte daha fazla bilgi olmadan, ilk URI’nın, Joe’dan Joe tanımlayıcı ile birlikte, nesillerindeki 147 nesli bir Kişi’yi almasıdır. İkincisinin Joe'yu almasını beklemelisin. Gerçekte ne istediğinizi, arayan müşterinizin tüm düğüm kümesini ve bunların kök Kişi ile URI'nizin son bağlamı arasındaki ilişkilerini alabilmesi olduğunu varsayalım. Bunu, aynı URI ile (bazı ek dekorasyonlarla birlikte) ve text/vnd.graphvizisteğinize göre Kabul et'i ( .dotgrafik gösterimi için IANA kayıtlı ortam türü olan) belirleyerek yapabilirsiniz . Bununla, URI’yi olarak değiştirin.

/Persons/Joe/Parents;generations=147?id={Joe.NotableAncestor.Id}#directed

Bir HTTP İstek Başlığı Accept: text/vnd.graphviz ile müşterilerinize Joe ve 147 nesiller arasındaki nesiller arası hiyerarşinin yönlendirilmiş grafiğini istediklerini açıkça belirtmelerini sağlayabilirsiniz;

Text / vnd.graphviz 'in parçası için önceden tanımlanmış bir semantiği olup olmadığından emin değilim, talimat aramada hiçbirini bulamadım. Bu ortam türü aslında önceden tanımlanmış parça bilgisine sahipse, uygun bir URI oluşturmak için semantiğinin izlenmesi gerekir. Ancak, bu anlambilim önceden tanımlanmamışsa, URI belirtimi, fragman tanımlayıcısının anlambiliminin sınırsız olduğunu ve bunun yerine sunucu tarafından tanımlandığını belirtir, bu kullanımı geçerli kılar.

3) Kaynağınızdaki "filtrelemenin" yanı sıra gerçekten kullanılan sorgu dizeleri nelerdir? İlk yaklaşıma girerseniz, filter parametresi URI'da sorgu dizesi parametresi yerine path parametresi olarak gömülür.

Bunu zaten ölüme kadar yendiğime inanıyorum, ancak sorgu dizeleri kaynakları "filtrelemek" için değil. Onlar içindir tanımlayan hiyerarşik olmayan verilerden kaynağınız. Eğer giderek yolu ile hiyerarşisinde aşağı delinmiş varsa /person/{id}/children/ve bir tespit etmek isteyen vardır spesifik çocuk veya belirli çocukların seti, size tespit ediyorlar grubuna uygulanır bazı özellik kullanmak ve onu sorguya içeride yer alacak.

Yanlış anladığın yer:

Müşterilerim bana bir kimlik referansı verirse

Bir REST sistemlerinde, müşteri asla kimliklerle rahatsız edilmemelidir. Müşterinin bilmesi gereken tek kaynak tanımlayıcıları URI'ler olmalıdır. Bu "homojen arayüz" ilkesidir.

Müşterilerin sisteminizle nasıl etkileşime gireceğini düşünün. Kullanıcının büyükanne ve büyükbaba listesine göz atmaya başladığını ve büyük anne babasının çocuğunu seçtiğini söyleyin /grandparent/123. Eğer müşteri çocukları arayabilirse /grandparent/123, o zaman "HATEOAS" a göre, bir sorgu yaptığınızda ne olursa olsun geri gönderilenler /grandparent/123arama arayüzüne bir URL döndürmelidir. Bu URL, içinde gömülü olan mevcut büyükbaba veya büyükanne tarafından filtrelenmek için gereken verilere zaten sahip olmalıdır.

Bağlantı benziyor olsun /grandparent/123?search={term}veya /parent?grandparent=123&search={term}ya /parent?grandparentTerm=someterm&someothergplocator=blah&search={term}DİNLENME göre önemsiz. Bu URL’lerin hepsinin, aynı {term}kriterleri kullanmasına rağmen , aynı sayıda parametreye sahip olduklarına dikkat edin. Bu URL'lerin herhangi biri arasında geçiş yapabilir veya belirli büyükanne ve büyükbabalara bağlı olarak bunları karıştırabilir ve müşteri bozmaz, çünkü temel uygulama önemli ölçüde farklılık gösterse de kaynaklar arasındaki mantıksal ilişki aynıdır.

Bunun yerine, hizmeti /grandparent/{grandparentID}?search={term}bir yoldan /children?parent={parentID}&search={term}giderken, a} başka bir yoldan giderken gerektirdiği şekilde yaratmış olsaydınız, bu çok fazla eşleşir, çünkü müşteri kavramsal olarak benzer farklı ilişkilerde farklı şeyleri enterpolasyona sokmak zorunda kalırdı.

Aslında beraber /grandparent/123?search={term}ya /parent?grandparent=123&search={term}da bir zevk meselesi olup olmadığı ve hangi uygulama olursa olsun şu anda sizin için daha kolay. Önemli olan, URL stratejinizi değiştirirseniz veya farklı ebeveyn-çocuk ilişkileri için farklı stratejiler kullanıyorsanız, müşterinin değiştirilmesini istememektir.

İnsanların kimlik değerlerini URL’ye sokmanın neden bir REST API'sı anlamına geldiğinden emin değilim, REST fiilleri kullanmak, kaynakları geçmekle ilgili.

Dolayısıyla, yeni bir kullanıcı yayınlamak istiyorsanız, adil bir veri yığını göndermeniz gerekir ve bir POST http isteği idealdir, bu nedenle anahtarı (örneğin kullanıcı kimliği) gönderebilseniz de, kullanıcı verilerini gönderirsiniz. (örneğin isim, adres) POST verisi olarak.

Şimdi, kaynak tanımlayıcısını URI'ye koymak yaygın bir deyimdir, ancak bu, "URI'da değilse REST değil" kurallı herhangi bir biçiminden daha gelenekseldir. Unutmayın , REST'in orijinal tezi , http'den gerçekten bahsetmiyor, bunun bir istemci-sunucudaki verileri ele alması için bir deyim, http'in bir uzantısı değil (tabii ki, http, REST'i uygulamanın birincil şeklidir) .

Örneğin, Fielding, bir akademik makalenin talebini örnek olarak kullanır. "Bira içerken Dr Dr's's Paper" kaynağını almak istiyorsunuz, ancak ilk sürümü veya en son sürümü de isteyebilirsiniz, bu nedenle kaynak tanımlayıcısı, kolayca tanımlanabilecek tek bir ID olarak referans alınabilecek bir şey olmayabilir. URI içine yerleştirilmiş. REST buna izin verir ve bunun arkasında belirtilen bir niyet:

REST, bunun yerine yazarın, tanımlanan kavramın yapısına en uygun olan bir kaynak tanımlayıcısı seçmesine dayanır.

Böylece, ebeveynlerinizi almak için statik bir URI kullanmanızdan, peşinde olduğunuz tam kullanıcıyı tanımlamak için sorgu dizesindeki bir arama teriminden geçmekten alıkoyacak hiçbir şey yoktur. Bu durumda, tanımladığınız 'kaynak' dedesi kümesidir (ve böylece URI, URI'nin bir parçası olarak 'büyükanne ve büyükbaba' içerir. REST, sizin hangi temsili göstermenizi belirlemek için tasarlanmış 'kontrol verileri' kavramını içerir. kaynak alınacak - bunlarda verilen örnek önbellek kontrolü değil, aynı zamanda sürüm kontrolüdür - bu nedenle Dr John'un mükemmel kağıdına olan isteğim, sürümü URI'nin bir parçası olarak kontrol verisi olarak geçirerek rafine edilebilir.

Genelde belirtilmeyen bir REST arayüzü örneği SMTP olduğunu düşünüyorum . Bir posta mesajı oluştururken, posta mesajının her bir kısmı için kaynak verilerini içeren fiiller (FROM, TO vb.) Gönderirsiniz. Bu, http fiillerini kullanmasa da RESTful'dır, kendi setini kullanır.

Öyleyse ... URI'nızda bir miktar kaynak kimliğine sahip olmanız gerekecek olsa da, kimlik referansınız olması gerekmez. Bu, kontrol dizisi olarak, sorgu dizesinde ve hatta POST verilerinde gönderilebilir. REST API'nizde gerçekten tanımladığınız şey, zaten URI'nızda bulunan bir çocuğun peşindesiniz.

Bu yüzden aklıma, REST'in tanımını okuyarak, hangisinin geri verilmesini istediğinizi belirlemek için kontrol verilerini (sorgulayıcı biçiminde) ileterek bir çocuk kaynağı talep ediyorsunuz. Sonuç olarak, büyükanne veya büyükbaba veya büyükbaba için URI isteği yapamazsınız. Çocuklarınızın iade edilmesini istersiniz, böylece ebeveyn / büyükbaba veya kimliği terimi kesinlikle böyle bir URI'de olmamalıdır. Çocuklar olmalı.

Pek çok insan zaten REST'in ne anlama geldiği vb. Hakkında konuştular. Fakat hiçbiri asıl meseleyi ele alıyor gibi görünmüyor: tasarımınız.

Büyükbaba veya büyükbabası neden babadan farklı? Her ikisinde de muhtemelen olabilecek ... ... çocukları olan çocukları var.

Sonunda, hepsi 'insan'. Muhtemelen bunu da kodunuzda bulabilirsiniz. Öyleyse şunu kullan:

GET /<api-endpoint>/humans/<ID>

İnsan hakkında bazı yararlı bilgiler verir. (İsim ve sayfalar)

GET /<api-endpoint>/humans/<ID>/children

belli ki bir dizi çocuğu geri getirecektir. Çocuk yoksa, boş bir dizi muhtemelen gidilecek yoldur.

Kolaylaştırmak için, örneğin bir 'hasChildren' bayrağı ekleyebilirsiniz. veya 'hasGrandChildren'.

Daha akıllıca düşünmek zor değil

Her grandparentID kendi URL'sini aldığı için aşağıdakiler daha RESTfull. Bu şekilde kaynak benzersiz bir şekilde tanımlanır.

GET /myservice/api/v1/grandparents/{grandparentID}
GET /myservice/api/v1/grandparents/{grandparentID}/parents/children?search={text}

Sorgu parametresi araması, bu kaynağın bağlamından bir arama yapmak için iyi bir yoldur.

Bir aile çok büyüdüğünde, örneğin sorgu / seçenek olarak start / limit kullanabilirsiniz:

GET /myservice/api/v1/grandparents/{grandparentID}/children?start=1&limit=50

Bir geliştirici olarak, benzersiz bir URL / URI ile farklı kaynaklara sahip olmak iyidir. Sorgu parametresini yalnızca dışarıda bırakılabildiklerinde kullanmanız gerektiğini düşünüyorum.

Belki de bu iyi bir okumadır http://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling ve Roy T Fielding'in orijinal doktora tezi https://www.ics.uci.edu /~fielding/pubs/dissertation/fielding_dissertation.pdf kavramları çok iyi ve eksiksiz açıklar.

İle gideceğim

/myservice/api/v1/people/{personID}/descendants/2?search={text}

Bu durumda, her önek geçerli bir kaynaktır:

• /myservice/api/v1/people: tüm insanlar
• /myservice/api/v1/people/{personID}: tam bilgiye sahip bir kişi (atalar, kardeşler, torunlar dahil)
• /myservice/api/v1/people/{personID}/descendants: bir kişinin soyundan
• /myservice/api/v1/people/{personID}/descendants/2: bir kişinin torunları

En iyi cevap olmayabilir, ama en azından bana mantıklı geliyor.

benden önce birçok kişi, URL formatının RESTful servis bağlamında önemsiz olduğuna dikkat çekti ... iki sentim olacaktı ... orijinal yazımda savunulan REST'in önemli bir yönü de “Kaynaklar” kavramıydı. URL’nizi tasarlarken aklınızda bulundurmanız gereken bir yönü, bir 'Kaynak’ın tek bir tabloda (satırda olmasına rağmen) bir satır olmamasıdır .. bunun yerine bir temsildir ... aynı zamanda tutarlıdır .. .ve bu temsili durumunda (ve etkili bir şekilde düşük depolama ortamına) değişiklik yapmak için kullanılabilir .. ve belirli bir kaynak sadece iş bağlamınız için anlamlı olabilir ... örneğin;

Örneğinizde / myservice / api / v1 / grandparents / {grandparentID} / ebeveynler / çocuklar? Search = {text}

Bunu kısaltırsanız daha anlamlı bir kaynak olabilir / myservice / api / v1 / siblingsOfGrandParents? Search = ..

bu durumda 'kardeşleriOfGrandParents' ı kaynak olarak ilan edebilirsiniz .. bu URL'yi basitleştirir

Diğerlerinin belirttiği gibi, bir URL'de etki alanları nesnesinin her tür hiyerarşik ilişkisine uymanız gerektiğine dair yaygın bir yanlış yönlendirilmiş görüş olduğu belirtiliyor. kaynakları ve tüm ilişkilerini temsil ediyor ... soru, inanmam gereken soruyu ... URL'lerle bu ilişkiyi açığa vurma ihtiyacım var ... özellikle yol segmentleri ... belki de değil.