REST API'leri için adlandırma kuralı yönergeleri var mı? [kapalı]

REST API'leri oluştururken, API içindeki kuralları adlandırmak için herhangi bir yönerge veya kusurlu standartlar var mı (ör. URL bitiş noktası yolu bileşenleri, sorgu dizesi parametreleri)? Deve kapakları norm mu yoksa alt çizgi mi? diğerleri?

Örneğin:

api.service.com/helloWorld/userId/x

veya

api.service.com/hello_world/user_id/x

Not: Bu RESTful API tasarımıyla ilgili bir sorun değil, kullanılan yol bileşenleri ve / veya kullanılan sorgu dizesi parametreleri için kullanılacak adlandırma kuralları kılavuzudur.

Herhangi bir yönerge takdir edilecektir.

Bence deve kapaklarından kaçınmalısınız. Norm, küçük harfler kullanmaktır. Ayrıca alt çizgilerden kaçınır ve bunun yerine tire kullanırım

URL'niz şöyle görünmelidir (istediğiniz gibi tasarım sorunlarını görmezden gelir :-))

api.service.com/hello-world/user-id/x

Dropbox , Twitter , Google Web Services ve Facebook için REST API alt çizgi kullanır.

Sıradan web kaynakları için URI'lere yakından bakın. Bunlar senin şablonun. Dizin ağaçlarını düşünün; Linux benzeri basit dosya ve dizin adlarını kullanın.

HelloWorldgerçekten iyi bir kaynak sınıfı değil. Bu bir "şey" gibi görünmüyor. Öyle olabilir, ama isim gibi değil. birgreeting bir şeydir.

user-idgetirdiğiniz bir isim olabilir. Ancak, isteğinizin sonucunun yalnızca bir kullanıcı_kimliği olduğundan şüpheleniliyor. İsteğin sonucunun bir Kullanıcı olması çok daha olasıdır. Bu nedenle, usergetirdiğiniz isim

www.example.com/greeting/user/x/

Bana mantıklı geldi. REST isteğinizi bir tür isim ifadesi yapmaya odaklayın - bir hiyerarşi (veya sınıflandırma veya dizin) üzerinden geçen bir yol. Mümkünse isim ifadelerinden kaçınarak mümkün olan en basit isimleri kullanın.

Genel olarak, bileşik ad ifadeleri genellikle hiyerarşinizde başka bir adım anlamına gelir. Yani sahip değilsin /hello-world/user/ve /hello-universe/user/. You have /hello/world/user/ve hello/universe/user/. Veya muhtemelen /world/hello/user/ve /universe/hello/user/.

Mesele, kaynaklar arasında bir gezinme yolu sağlamaktır.

'UserId' tamamen yanlış bir yaklaşımdır. Fiil (HTTP Yöntemleri) ve İsim yaklaşımı, Roy Fielding'in REST mimarisi için kastettiği şeydir . İsimler:

1. Bir şeyler koleksiyonu
2. Bir şey

İyi bir adlandırma kuralı:

[POST or Create](To the *collection*)
sub.domain.tld/class_name.{media_type} 

[GET or Read](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[PUT or Update](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[DELETE](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[GET or Search](of a *collection*, FRIENDLY URL)
sub.domain.tld/class_name.{media_type}/{var}/{value}/{more-var-value-pairs}

[GET or Search](of a *collection*, Normal URL)
sub.domain.tld/class_name.{media_type}?var=value&more-var-value-pairs

{Media_type} şunlardan biridir: json, xml, rss, pdf, png, hatta html.

Sonuna bir 's' ekleyerek koleksiyonu ayırt etmek mümkündür, örneğin:

'users.json' *collection of things*
'user/id_value.json' *single thing*

Ancak bu, 's'leri nereye koyduğunuzu ve nereye koymadığınızı takip etmeniz gerektiği anlamına gelir. Ayrıca gezegenin yarısı (yeni başlayanlar için Asyalılar), açık çoğulları olmayan dilleri konuşur, böylece URL onlar için daha az dost olur.

Hayır. REST'in URI adlandırma kurallarıyla hiçbir ilgisi yoktur. Bu kuralları API'nizin bir parçası olarak bant dışı, yalnızca köprü metni olarak dahil ederseniz, API'nız RESTful değildir.

Daha fazla bilgi için, bkz. Http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Alan adları büyük / küçük harfe duyarlı değildir, ancak URI'nin geri kalanı kesinlikle olabilir. URI'lerin büyük / küçük harfe duyarlı olmadığını varsaymak büyük bir hatadır.

Ürünlerde kullandığımız http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html adresinde bir kılavuz listem var. Yönergeler her zaman tartışmalıdır ... Bence tutarlılık bazen işleri mükemmel hale getirmekten daha önemlidir (eğer böyle bir şey varsa).

Bu örnekte deve davasının sorun olduğunu düşünmüyorum, ancak yukarıdaki örnek için daha RESTful adlandırma kuralı olacağını hayal ediyorum:

api.service.com/helloWorld/userId/x

daha sonra userId'i bir sorgu parametresi (mükemmel bir şekilde yasal olan) yapmak örneğim bu kaynağı IMO'da daha RESTful bir şekilde gösterir.

Müşterilerinizi Oauth2 ile doğrularsanız, parametre adlarınızdan en az ikisinin altını çizmeniz gerektiğini düşünüyorum:

• Müşteri Kimliği
• client_secret

CamelCase'i (henüz yayınlanmadı) REST API'mde kullandım. API belgelerini yazarken, diğer parametreler olmasa da Oauth parametrelerinin neden snake_case olduğunu açıklamak zorunda olmadığım için her şeyi snake_case olarak değiştirmeyi düşünüyordum.

Bkz. Https://tools.ietf.org/html/rfc6749

REST URL'lerinde mümkün olduğunca az özel karakter kullanmanın tercih edilebilir olduğunu söyleyebilirim. REST'in avantajlarından biri, bir hizmet için "arabirimi" okumayı kolaylaştırmasıdır. Deve durumu veya Pascal durumu muhtemelen kaynak adları için iyidir (Kullanıcılar veya kullanıcılar). REST çevresinde gerçekten zor standartlar olduğunu düşünmüyorum.

Ayrıca, Gandalf haklı olduğunu düşünüyorum, genellikle sorgu dizesi parametrelerini kullanmak değil, bunun yerine hangi kaynakları ele almak istediğinizi tanımlayan yollar oluşturmak REST daha temiz.

http://api.example.com/HelloWorld/Users/12345/Order/3/etc