Apakah ada pedoman konvensi penamaan untuk REST API? [Tutup]

Saat membuat REST API, apakah ada pedoman atau standar defacto untuk penamaan konvensi dalam API (mis .: komponen jalur titik akhir URL, parameter kueri)? Apakah topi unta adalah norma, atau garis bawah? orang lain?

Sebagai contoh:

api.service.com/helloWorld/userId/x

atau

api.service.com/hello_world/user_id/x

Catatan: Ini bukan pertanyaan tentang RESTful API design, melainkan panduan konvensi penamaan yang akan digunakan untuk komponen lintasan akhirnya dan / atau parameter string kueri yang digunakan.

Pedoman apa pun akan dihargai.

Saya pikir Anda harus menghindari topi unta. Normalnya adalah menggunakan huruf kecil. Saya juga akan menghindari garis bawah dan menggunakan tanda hubung sebagai gantinya

Jadi URL Anda akan terlihat seperti ini (mengabaikan masalah desain seperti yang Anda minta :-))

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

API REST untuk Dropbox , Twitter , Layanan Web Google , dan Facebook semuanya menggunakan garis bawah.

Perhatikan baik-baik sumber daya web biasa di URI. Itu adalah templat Anda. Pikirkan pohon direktori; menggunakan nama file dan direktori seperti Linux yang sederhana.

HelloWorldbukan kelas sumber daya yang benar-benar bagus. Tampaknya tidak menjadi "benda". Mungkin, tapi itu tidak seperti kata benda. A greetingadalah suatu hal.

user-idmungkin kata benda yang Anda ambil. Namun, diragukan bahwa hasil permintaan Anda hanya user_id. Ini jauh lebih mungkin bahwa hasil dari permintaan adalah Pengguna. Karenanya, useradalah kata benda yang Anda ambil

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

Masuk akal bagi saya. Berfokuslah untuk membuat REST Anda meminta semacam frase kata benda - jalur melalui hierarki (atau taksonomi, atau direktori). Gunakan kata benda sesederhana mungkin, hindari frasa kata benda jika memungkinkan.

Secara umum, frase nomina majemuk biasanya berarti langkah lain dalam hierarki Anda. Jadi kamu tidak punya /hello-world/user/dan /hello-universe/user/. Anda punya /hello/world/user/dan hello/universe/user/. Atau mungkin /world/hello/user/dan /universe/hello/user/.

Intinya adalah untuk menyediakan jalur navigasi di antara sumber daya.

'UserID' sepenuhnya merupakan pendekatan yang salah. Pendekatan Verb (Metode HTTP) dan Noun adalah yang dimaksud Roy Fielding untuk arsitektur REST . Kata benda adalah:

1. Sebuah Koleksi dari hal-hal
2. Suatu hal

Satu konvensi penamaan yang baik adalah:

[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

Di mana {media_type} adalah salah satu dari: json, xml, rss, pdf, png, bahkan html.

Dimungkinkan untuk membedakan koleksi dengan menambahkan 's' di bagian akhir, seperti:

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

Tetapi ini berarti Anda harus melacak di mana Anda telah menempatkan 's' dan di mana Anda belum. Plus setengah dari planet ini (orang Asia untuk pemula) berbicara bahasa tanpa bentuk jamak eksplisit sehingga URL kurang ramah bagi mereka.

Tidak. REST tidak ada hubungannya dengan konvensi penamaan URI. Jika Anda memasukkan konvensi ini sebagai bagian dari API Anda, out-of-band, bukan hanya melalui hypertext, maka API Anda tidak TENANG.

Untuk informasi lebih lanjut, lihat http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Nama domain tidak peka terhadap huruf besar tetapi sisa URI tentu saja bisa. Adalah kesalahan besar untuk menganggap URI tidak peka terhadap huruf besar-kecil.

Saya memiliki daftar pedoman di http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html yang telah kami gunakan dalam prod. Pedoman selalu dapat diperdebatkan ... Saya pikir konsistensi kadang-kadang lebih penting daripada mendapatkan hal-hal yang sempurna (jika ada hal seperti itu).

Saya tidak berpikir kasus unta adalah masalah dalam contoh itu, tetapi saya membayangkan konvensi penamaan yang lebih tenang untuk contoh di atas adalah:

api.service.com/helloWorld/userId/x

alih-alih membuat userId parameter kueri (yang benar-benar legal) contoh saya menunjukkan sumber daya itu, IMO, cara yang lebih tenang.

Jika Anda mengautentikasi klien Anda dengan Oauth2 saya pikir Anda akan perlu menggarisbawahi untuk setidaknya dua nama parameter Anda:

• client_id
• client_secret

Saya telah menggunakan camelCase di API SISA saya (belum diterbitkan). Saat menulis dokumentasi API saya telah berpikir untuk mengubah segalanya menjadi snake_case jadi saya tidak perlu menjelaskan mengapa param Oauth adalah snake_case sedangkan param lainnya tidak.

Lihat: https://tools.ietf.org/html/rfc6749

Saya akan mengatakan bahwa lebih baik menggunakan karakter khusus sesedikit mungkin dalam URL REST. Salah satu manfaat REST adalah membuat "antarmuka" untuk layanan mudah dibaca. Casing unta atau Cascal case mungkin baik untuk nama sumber daya (Pengguna atau pengguna). Saya tidak berpikir ada standar keras di sekitar REST.

Juga, saya pikir Gandalf benar, biasanya lebih bersih di REST untuk tidak menggunakan parameter string kueri, tetapi malah membuat jalur yang menentukan sumber daya mana yang ingin Anda tangani.

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