Apa praktik terbaik untuk sumber daya bersarang REST?

Sejauh yang saya tahu setiap sumber daya individu harus hanya memiliki satu jalur kanonik . Jadi, dalam contoh berikut, apa yang akan menjadi pola URL yang baik?

Ambil contoh, perwakilan dari Perusahaan. Dalam contoh hipotetis ini, setiap perusahaan memiliki 0 atau lebih departemen dan masing-masing departemen memiliki 0 atau lebih karyawan.

Departemen tidak dapat eksis tanpa perusahaan terkait.

Seorang karyawan tidak dapat ada tanpa departemen terkait.

Sekarang saya akan menemukan representasi alami dari pola sumber daya.

• /companies Kumpulan perusahaan - Menerima penempatan untuk perusahaan baru. Dapatkan untuk seluruh koleksi.
• /companies/{companyId}Perusahaan individual. Terima DAPATKAN, PUT dan HAPUS
• /companies/{companyId}/departmentsMenerima POST untuk item baru. (Menciptakan departemen dalam perusahaan.)
• /companies/{companyId}/departments/{departmentId}/
• /companies/{companyId}/departments/{departmentId}/employees
• /companies/{companyId}/departments/{departmentId}/employees/{empId}

Mengingat kendala, di setiap bagian, saya merasa ini masuk akal jika agak bersarang.

Namun, kesulitan saya datang jika saya ingin mendaftar ( GET) semua karyawan di semua perusahaan.

Pola sumber daya untuk yang paling dekat akan dipetakan ke /employees(Pengumpulan semua karyawan)

Apakah itu berarti saya seharusnya /employees/{empId}juga karena jika demikian maka ada dua URI untuk mendapatkan sumber daya yang sama?

Atau mungkin seluruh skema harus diratakan tetapi itu berarti bahwa karyawan adalah objek tingkat atas yang bersarang.

Pada tingkat dasar /employees/?company={companyId}&department={deptId}mengembalikan pandangan yang sama persis tentang karyawan sebagai pola yang paling bersarang.

Apa praktik terbaik untuk pola URL di mana sumber daya dimiliki oleh sumber daya lain tetapi harus dapat digunakan secara terpisah?

Apa yang Anda lakukan benar. Secara umum bisa ada banyak URI dengan sumber daya yang sama - tidak ada aturan yang mengatakan Anda tidak boleh melakukan itu.

Dan umumnya, Anda mungkin perlu mengakses item secara langsung atau sebagai bagian dari sesuatu yang lain - jadi struktur Anda masuk akal bagi saya.

Hanya karena karyawan dapat diakses di bawah departemen:

company/{companyid}/department/{departmentid}/employees

Bukan berarti mereka tidak dapat diakses di bawah perusahaan juga:

company/{companyid}/employees

Yang akan mengembalikan karyawan untuk perusahaan itu. Itu tergantung pada apa yang dibutuhkan oleh klien Anda - itulah yang harus Anda rancang.

Tetapi saya berharap bahwa semua penangan URL menggunakan kode dukungan yang sama untuk memenuhi permintaan sehingga Anda tidak menggandakan kode.

Saya sudah mencoba kedua strategi desain - titik akhir bersarang dan tidak bersarang. Saya telah menemukan bahwa:

1. Jika sumber daya bersarang memiliki kunci utama dan Anda tidak memiliki kunci utama induknya, struktur bersarang mengharuskan Anda untuk mendapatkannya, meskipun sistem sebenarnya tidak memerlukannya.

2. titik akhir bersarang biasanya membutuhkan titik akhir redundan. Dengan kata lain, Anda akan lebih sering membutuhkan titik akhir tambahan / karyawan sehingga Anda bisa mendapatkan daftar karyawan lintas departemen. Jika Anda memiliki / karyawan, apa sebenarnya yang dibeli / perusahaan / departemen / karyawan Anda?

3. titik akhir bersarang tidak berevolusi dengan baik. Misalnya Anda mungkin tidak perlu mencari karyawan sekarang tetapi Anda mungkin nanti dan jika Anda memiliki struktur bersarang, Anda tidak punya pilihan selain menambahkan titik akhir lain. Dengan desain non-bersarang, Anda hanya menambahkan lebih banyak parameter, yang lebih sederhana.

4. terkadang sumber daya bisa memiliki banyak tipe orang tua. Menghasilkan banyak titik akhir semua mengembalikan sumber daya yang sama.

5. titik akhir yang berlebihan membuat dokumen lebih sulit untuk ditulis dan juga membuat api lebih sulit untuk dipelajari.

Singkatnya, desain non-bersarang tampaknya memungkinkan skema titik akhir yang lebih fleksibel dan sederhana.

Saya telah memindahkan apa yang telah saya lakukan dari pertanyaan ke sebuah jawaban di mana lebih banyak orang akan melihatnya.

Apa yang telah saya lakukan adalah memiliki titik akhir pembuatan di titik akhir bersarang, Titik akhir kanonik untuk memodifikasi atau meminta item tidak berada di sumber daya bersarang .

Jadi dalam contoh ini (cukup cantumkan titik akhir yang mengubah sumber daya)

• POST /companies/ membuat perusahaan baru mengembalikan tautan ke perusahaan yang dibuat.
• POST /companies/{companyId}/departments ketika suatu departemen diletakkan menciptakan departemen baru mengembalikan tautan ke /departments/{departmentId}
• PUT /departments/{departmentId} memodifikasi departemen
• POST /departments/{deparmentId}/employees membuat karyawan baru mengembalikan tautan ke /employees/{employeeId}

Jadi ada sumber daya level root untuk setiap koleksi. Namun buat adalah di objek yang dimiliki .

Saya sudah membaca semua jawaban di atas tetapi sepertinya mereka tidak memiliki strategi yang sama. Saya menemukan artikel yang bagus tentang praktik terbaik dalam API Desain dari Dokumen Microsoft . Saya pikir Anda harus merujuk.

Dalam sistem yang lebih kompleks, mungkin tergoda untuk menyediakan URI yang memungkinkan klien untuk menavigasi melalui beberapa tingkat hubungan, seperti /customers/1/orders/99/products.Namun, tingkat kompleksitas ini mungkin sulit dipertahankan dan tidak fleksibel jika hubungan antar sumber daya berubah di masa depan. Sebagai gantinya, cobalah untuk menjaga URI relatif sederhana . Setelah aplikasi memiliki referensi ke sumber daya, seharusnya dimungkinkan untuk menggunakan referensi ini untuk menemukan item yang terkait dengan sumber daya itu. Permintaan sebelumnya dapat diganti dengan URI /customers/1/ordersuntuk menemukan semua pesanan untuk pelanggan 1, dan kemudian /orders/99/productsuntuk menemukan produk dalam pesanan ini.

.

Tip

Hindari membutuhkan URI sumber daya yang lebih kompleks daripada collection/item/collection.

Tampilan URL Anda tidak ada hubungannya dengan REST. Apapun itu. Ini sebenarnya adalah "detail implementasi". Jadi sama seperti bagaimana Anda memberi nama variabel Anda. Mereka harus unik dan tahan lama.

Jangan buang waktu terlalu banyak untuk hal ini, buat saja pilihan dan tetaplah konsisten / konsisten. Misalnya jika Anda menggunakan hierarki maka Anda melakukannya untuk semua sumber daya Anda. Jika Anda menggunakan parameter kueri ... dll seperti halnya penamaan konvensi dalam kode Anda.

Kenapa begitu ? Sejauh yang saya tahu, API "RESTful" harus dapat dijelajahi (Anda tahu ... "Hypermedia sebagai Engine of Application State"), oleh karena itu klien API tidak peduli tentang seperti apa URL Anda asalkan URL mereka valid (tidak ada SEO, tidak ada manusia yang perlu membaca "url ramah" itu, kecuali mungkin untuk debugging ...)

Seberapa bagus / mudah dimengerti URL dalam REST API hanya menarik bagi Anda sebagai pengembang API, bukan klien API, seperti halnya nama variabel dalam kode Anda.

Yang paling penting adalah klien API Anda tahu cara menginterpretasikan tipe media Anda. Misalnya tahu bahwa:

• tipe media Anda memiliki properti tautan yang mencantumkan tautan yang tersedia / terkait.
• Setiap tautan diidentifikasi oleh suatu hubungan (seperti halnya browser tahu bahwa tautan [rel = "stylesheet"] berarti lembar gaya atau rel = favico adalah tautan ke favicon ...)
• dan diketahui apa arti hubungan itu ("perusahaan" berarti daftar perusahaan, "pencarian" berarti url templated untuk melakukan pencarian pada daftar sumber daya, "departemen" berarti departemen dari sumber daya saat ini)

Di bawah ini adalah contoh pertukaran HTTP (badan berada di yaml karena lebih mudah untuk menulis):

Permintaan

GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml

Respons: daftar tautan ke sumber daya utama (perusahaan, orang, apa pun ...)

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:04:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: this is your API's entrypoint (like a homepage)  
links:
  # could be some random path https://api.acme.local/modskmklmkdsml
  # the only thing the API client cares about is the key (or rel) "companies"
  companies: https://api.acme.local/companies
  people: https://api.acme.local/people

Permintaan: tautan ke perusahaan (menggunakan body.links.companies respons sebelumnya)

GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml

Respons: sebagian daftar perusahaan (di bawah item), sumber daya tersebut berisi tautan terkait, seperti tautan untuk mendapatkan pasangan perusahaan berikutnya (body.links.next) tautan lain (templated) untuk pencarian (body.links.search)

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:06:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: representation of a list of companies
links:
  # link to the next page
  next: https://api.acme.local/companies?page=2
  # templated link for search
  search: https://api.acme.local/companies?query={query} 
# you could provide available actions related to this resource
actions:
  add:
    href: https://api.acme.local/companies
    method: POST
items:
  - name: company1
    links:
      self: https://api.acme.local/companies/8er13eo
      # and here is the link to departments
      # again the client only cares about the key department
      department: https://api.acme.local/companies/8er13eo/departments
  - name: company2
    links:
      self: https://api.acme.local/companies/9r13d4l
      # or could be in some other location ! 
      department: https://api2.acme.local/departments?company=8er13eo

Jadi seperti yang Anda lihat jika Anda membuka tautan / hubungan dengan cara Anda menyusun bagian jalur URL Anda tidak memiliki nilai apa pun untuk klien API Anda. Dan jika Anda mengkomunikasikan struktur URL Anda kepada klien Anda sebagai dokumentasi, maka Anda tidak melakukan REST (atau setidaknya bukan Level 3 sesuai " model jatuh tempo Richardson ")

Saya tidak setuju dengan jalan seperti ini

GET /companies/{companyId}/departments

Jika Anda ingin mendapatkan departemen, saya pikir lebih baik menggunakan sumber daya / departemen

GET /departments?companyId=123

Saya kira Anda memiliki companiestabel dan departmentstabel kemudian kelas untuk memetakannya dalam bahasa pemrograman yang Anda gunakan. Saya juga berasumsi bahwa departemen dapat dilampirkan ke entitas lain selain perusahaan, sehingga sumber daya / departemen mudah, lebih mudah untuk memiliki sumber daya yang dipetakan ke tabel dan juga Anda tidak memerlukan banyak titik akhir karena Anda dapat menggunakan kembali

GET /departments?companyId=123

untuk segala jenis pencarian, misalnya

GET /departments?name=xxx
GET /departments?companyId=123&name=xxx
etc.

Jika Anda ingin membuat departemen,

POST /departments

sumber daya harus digunakan dan badan permintaan harus berisi ID perusahaan (jika departemen hanya dapat ditautkan dengan satu perusahaan).

Rails memberikan solusi untuk ini: bersarang dangkal .

Saya pikir ini bagus karena ketika Anda berurusan langsung dengan sumber daya yang dikenal, tidak perlu menggunakan rute bersarang, seperti yang telah dibahas dalam jawaban lain di sini.