Bir alt nesne göndermek ve tüm ebeveynlerin tüm alt öğelerini almak için API uç noktaları nasıl tasarlanır?

Örneğin varlıklarım var: Müşteri, Rapor. Müşteri birçok Rapor içerebilir ve tek bir Rapor yönetimi için uç nokta bu şekilde iç içe olması gerektiğini düşünüyorum:

/clients/{client_id}/reports/{report_id}

Bir müşterinin tüm raporlarına gelince, enpoint bekleniyor:

/clients/{client_id}/reports

Ancak, API'nın tutarlı ve iyi tasarlanmış olmasını sağlamak için tüm İstemcilerin Tüm Raporlarını almak için nasıl bir uç noktaya bakılmalıdır?

Yaklaşımlarım:

1. (Bazı Google API'larında gördüm) yerine "-" kullanın ve "all" olarak ayrıştırın:

/clients/-/reports

Bu, uç nokta biçimini aynı tutar, ancak biraz alışılmadık görünür, bu şekilde öneren herhangi bir rfc bulamaz.

2. Yalnızca tüm raporlar için ayrı bir uç nokta oluşturun:

/reports

Ancak Müşterinin Raporlarını almak için hala:

/clients/{client_id}/reports

3. "Müşteri" yi bir üst öğe değil, yalnızca bir filtre parametresi yapmak için refactor uç noktaları:

/reports?client={client_id} - bir müşterinin raporları

/reports - tüm müşterinin raporları

Belirli bir istemciye rapor göndermek için yeni bir bitiş noktası eklenmesi durumunda, URL'de bir parametre içeren bir POST isteği olacağı için çirkin görünebilir.

Başka fikir önerileri var mı?

Ancak, API'nın tutarlı ve iyi tasarlanmış olmasını sağlamak için tüm İstemcilerin Tüm Raporlarını almak için nasıl bir uç noktaya bakılmalıdır?

Her şeyden önce, RESTful API'leri modellemek için altın kuralların olmadığını unutmayın. Tüm sahip olduğumuz en iyi uygulamalar ve sözleşmeler. Bununla birlikte, olası cevap - her zamanki gibi - gereksinimlerinizi en iyi karşılayanı ve bu durumda modelinizi en iyi ifade eden cevabı seçin.

Bu yüzden ifadeden üç seçeneği kontrol edin.

# 1 "-" gösterimi

Bu parlak bir fikir. Bu bize durumu ifade etmesini sağlar tüm reportsbu aittir içinclients . "Sorguyu" belirli bir rapor kümesine ( clientssınır içinde bulunanlar ) daraltır .

Hiyerarşi (ait olma) kavramını her zaman korur, bu nedenle reportsfarklı yerlerde bulunabilirse, bu gösterim önemli bir şeydir. Örneğin:

• Müşterilere ait tüm raporlar /clients/-/reports
• Bölümlere ait tüm raporlar /departments/-/reports
• Çalışanlara ait tüm raporlar /employees/-/reports

Ancak, sistemdeki tüm kullanılabilir raporları almak için, hiyerarşiyi korumak bir sonraki seçeneğe göre önemli bir avantaj sağlamaz.

# 2 Farklı URI

Mevcut tüm raporları alırken sınırları / bağlamları / hiyerarşiyi ifade etmemiz gerekmiyorsa , bu yaklaşım benim için daha makul görünmektedir.

Yeni URI ( /reports) ayrıca bir rapor yönetimi olasılığını da açık bırakır . Ancak, gerekli görmezsek, tam bir RESTful desteği sağlamak zorunda değiliz. Örneğin, ifade ettiniz Make a separate endpoint just for all the reports. Sorun değil, sadece GETsorgulama için bazı filtreler uygulamanız ve belki de bazı filtreler uygulamanız yeterlidir.

Bunu hala yapabileceğinizi unutmayın /reports?client={client_id}. Aynı kaynak için farklı URI'ye sahip olmak iyidir. Okuduğum bazı makaleler buna sağlamlık der .

# 3 Hiyerarşiyi geri alma

Bu yaklaşımın beklentilerinizi karşılamadığını hissediyorum. Ayrıca, sanırım, sonunda sizi başlangıç ​​noktasına getirecektir.

Sonuçlar

# 1 ve # 2'nin birbirini dışlamadığını unutmayın. Her ikisini de uygulayabiliriz. Gerçek durum göz önüne alındığında ve OP'nin tesislerine göre sadece # 2 uygulayacağım.

^{1: /clients/-/reportssanırım bu}

Google'ın API tasarım kalıpları bu senaryoda '-' kullanılmasını önerir.

GET /clients/-/reports

Kaynak:

https://cloud.google.com/apis/design/design_patterns#list_sub-collections