Bir RESTful API'de sorgu parametrelerine karşı yol parametrelerini ne zaman kullanırım?

RESTful API'mi oldukça tahmin edilebilir yapmak istiyorum. Sorgu parametrelerini kullanmak yerine URI'yi kullanarak bir veri segmentasyonunun ne zaman yapılacağına karar vermek için en iyi uygulama nedir.

Sayfalamayı, sıralamayı ve gruplandırmayı destekleyen sistem parametrelerinin "?" İşaretinden sonra gelmesi bana mantıklı geliyor. Peki ya koleksiyonunuzu bölümlere ayıran 'durum' ve 'bölge' gibi alanlar veya diğer özellikler? Bunlar sorgu parametreleri de olacaksa, yol parametrelerinin ne zaman kullanılacağını bilmenin temel kuralı nedir?

RESTful API tasarımı için en iyi uygulama, belirli bir kaynağı veya kaynakları tanımlamak için yol parametreleri kullanılırken, bu kaynakları sıralamak / filtrelemek için sorgu parametreleri kullanılır.

İşte bir örnek. Araba adlı bir varlık için RESTful API uç noktaları uyguladığınızı varsayalım. Uç noktalarınızı şu şekilde yapılandırırsınız:

GET /cars
GET /cars/:id
POST /cars
PUT /cars/:id
DELETE/cars/:id

Bu şekilde, yalnızca hangi kaynağın getirileceğini belirlerken yol parametrelerini kullanırsınız, ancak bu, kaynakları hiçbir şekilde sıralamaz / filtrelemez.

Şimdi, GET isteklerinize arabaları renge göre filtreleme özelliğini eklemek istediğinizi varsayalım. Renk bir kaynak olmadığından (bir kaynağın özelliğidir), bunu yapan bir sorgu parametresi ekleyebilirsiniz. Bu sorgu parametresini GET/cars isteğinize şu şekilde eklersiniz :

ALMAK /cars?color=blue

Bu uç nokta, yalnızca mavi arabaların iade edilmesi için uygulanacaktı.

Sözdizimi söz konusu olduğunda, URL adlarınızın tümü küçük harf olmalıdır. Genelde İngilizce'de iki kelime olan bir varlık adınız varsa, deve harflerini değil, sözcükleri ayırmak için kısa çizgi kullanırsınız.

Ör. /two-words

Bu konu hakkında düşünmenin temel yolu şudur:

Bir URI, bir kaynak TÜRÜ'nün belirli bir örneğini benzersiz şekilde tanımlayan bir kaynak tanımlayıcıdır. Hayattaki diğer her şey gibi, her nesne (bazı türlerin bir örneği olan), zamanla değişmeyen veya zamansal niteliklere sahiptir.

Yukarıdaki örnekte bir araba, marka, model ve VIN gibi niteliklere sahip - asla değişmeyen ve zamanla değişebilen renk, süspansiyon vb. Özelliklere sahip çok somut bir nesnedir. Dolayısıyla, URI'yi zaman içinde değişebilen özniteliklerle (zamansal) kodlarsak, aynı nesne için birden çok URI ile sonuçlanabilir:

GET /cars/honda/civic/coupe/{vin}/{color=red}

Ve yıllar sonra, bu aynı arabanın rengi siyaha dönerse:

GET /cars/honda/civic/coupe/{vin}/{color=black}

Araba örneğinin kendisinin (nesnenin) değişmediğini unutmayın - sadece değişen renktir. Aynı nesne örneğini gösteren birden çok URI'ye sahip olmak, sizi birden çok URI işleyicisi oluşturmaya zorlar - bu verimli bir tasarım değildir ve elbette sezgisel değildir.

Bu nedenle, URI yalnızca hiçbir zaman değişmeyecek ve ömrü boyunca bu kaynağı benzersiz şekilde tanımlamaya devam edecek parçalardan oluşmalıdır. Değişebilecek her şey, aşağıdaki gibi sorgu parametreleri için ayrılmalıdır:

GET /cars/honda/civic/coupe/{vin}?color={black}

Alt satır - polimorfizmi düşünün.

Bir REST API'de, öngörülebilir URI'larla fazla ilgilenmemelisiniz. URI öngörülebilirliğinin önerisi, RESTful mimarisinin yanlış anlaşılmasına işaret ediyor. Bir müşterinin URI'leri kendilerinin oluşturması gerektiğini varsayar, ki bunu gerçekten yapmamaları gerekir.

Ancak, gerçek bir REST API değil, 'REST'den ilham alan' bir API (Google Drive gibi) oluşturduğunuzu varsayıyorum. Bu durumlarda temel kural, 'yol parametreleri = kaynak tanımlama' ve 'sorgu parametreleri = kaynak sıralama' şeklindedir. Öyleyse, soru şu hale gelir, kaynağınızı durum / bölge OLMADAN benzersiz bir şekilde tanımlayabilir misiniz? Cevabınız evet ise, o zaman belki bir sorgu parametresi. Hayır ise, o zaman bir yol parametresidir.

HTH.

Bir zamanlar ana kaynağın olduğu bir API tasarladım people. Genellikle kullanıcılar filtrelenmeyi talep ederlerdi, peopleböylece kullanıcıların /people?settlement=urbanher seferinde olduğu gibi bir şeyi aramasını önlemek için , /people/urbandaha sonra kolayca eklememi sağlayan uyguladım /people/rural. Ayrıca bu, /peopledaha sonra herhangi bir kullanım olacaksa tam listeye erişim sağlar . Kısacası, benim mantığım ortak alt kümelere bir yol eklemekti

Gönderen burada :

Yaygın sorgular için takma adlar

API deneyimini ortalama bir tüketici için daha keyifli hale getirmek için, koşul kümelerini kolayca erişilebilir RESTful yollara paketlemeyi düşünün. Örneğin, yukarıdaki yakın zamanda kapatılan biletler sorgusu şu şekilde paketlenebilir:GET /tickets/recently_closed

Genel olarak konuşursak, kaynakta açık bir 'hiyerarşi' olduğunda yol parametrelerini kullanma eğilimindeyim, örneğin:

/region/state/42

Bu tek kaynağın bir durumu varsa, aşağıdakilerden biri yapılabilir:

/region/state/42/status

Bununla birlikte, eğer 'bölge' açığa çıkan kaynağın gerçekten bir parçası değilse, muhtemelen sorgu parametrelerinden birine aittir - sayfalandırmaya benzer (bahsettiğiniz gibi).

Segmentasyon daha hiyerarşiktir ve "güzeldir" ancak sınırlayıcı olabilir.

Örneğin, üç segmentli bir url'niz varsa, her biri marka, model ve renk yoluyla bir araba aramak için farklı parametreler geçirir:

www.example.com/search/honda/civic/blue

Bu çok güzel bir url ve son kullanıcı tarafından daha kolay hatırlanıyor, ama şimdi bu yapıya takılıp kaldınız. Arama sırasında kullanıcının TÜM mavi arabaları veya TÜM Honda Civics'i arayabilmesi için bunu yapmak istediğinizi varsayalım. Bir sorgu parametresi bunu çözer çünkü bir anahtar-değer çifti verir. Böylece geçebilirsin:

www.example.com/search?color=blue
www.example.com/search?make=civic

Artık değere anahtarı aracılığıyla başvurmanın bir yolu var - sorgu kodunuzda "renk" veya "yap".

Aşağıdakiler gibi bir tür anahtar değer yapısı oluşturmak için muhtemelen daha fazla segment kullanarak bunu aşabilirsiniz:

www.example.com/search/make/honda/model/civic/color/blue

Umarım mantıklıdır ..

Örnek URL: /rest/{keyword}

Bu URL, yol parametreleri için bir örnektir. Bu URL verilerini kullanarak elde edebiliriz @PathParam.

Örnek URL: /rest?keyword=java&limit=10

Bu URL, sorgu parametreleri için bir örnektir. Bu URL verilerini kullanarak elde edebiliriz @Queryparam.