Desain API yang tenang. Apa yang harus saya kembalikan jika tidak ada baris?

Saat ini saya sedang mengkode API untuk jejaring sosial dengan Slim Framework. Pertanyaan saya adalah: Apa praktik terbaik ketika tidak ada baris untuk kembali dalam struktur json?

Katakanlah panggilan / v1 / get / film ini mengembalikan 2 baris dari nama film tabel:

[
    {"name": "Ghostbusters"},
    {"name": "Indiana Jones"}
]

Tapi, kemudian saya panggil / v1 / get / books dan tidak ada baris di tabel itu. Haruskah saya mengembalikan struktur kosong?

[
]

... atau lebih baik pesan dan kode kesalahan?

[
    "errors": {
        "message": "no matches found",
        "code": 134
    }
]

Yang merupakan praktik yang lebih baik? (API akan digunakan di aplikasi iOS dan Android) Terima kasih!

Biasanya saya akan mengembalikan jumlah rekaman sebagai metadata. Saya tidak yakin apakah itu praktik REST yang normal, tetapi tidak banyak data tambahan, dan sangat tepat. Biasanya ada pagination untuk banyak layanan, tidak praktis untuk mengembalikan resultset besar sekaligus. Secara pribadi saya kesal ketika ada pagination untuk set hasil kecil .. Jika kosong, kembalikan number_of_records : 0dan buku sebagai daftar / array kosong books : [].

{
    meta: {
        number_of_records : 2,
        records_per_page : 10,
        page : 0
    },
    books : [
        {id:1},
        {id:27}
    ]
}

EDIT (beberapa tahun kemudian): Jawaban dari Martin Wickman jauh lebih baik, inilah "penjelasan singkat" mengapa.

Ketika berhadapan dengan pagination selalu ingat kemungkinan konten atau pemesanan berubah. Seperti, permintaan pertama datang, 24 hasil, Anda kembali pertama 10. Setelah itu, "buku baru" dimasukkan dan sekarang Anda memiliki 25 hasil, tetapi dengan permintaan asli itu akan datang dipesan di tempat ke-10. Ketika pengguna pertama meminta halaman ke-2, ia tidak akan mendapatkan "buku baru". Ada beberapa cara untuk mengatasi masalah seperti itu, seperti menyediakan "id permintaan" yang harus dikirim dengan panggilan API berikut, kemudian mengembalikan halaman berikutnya dari set hasil "lama", yang harus disimpan entah bagaimana dan terikat dengan "permintaan id". Alternatifnya adalah menambahkan bidang seperti "daftar hasil diubah sejak permintaan pertama".

Secara umum, jika Anda bisa, cobalah untuk melakukan upaya ekstra dan menghindari pagination. Pagination adalah status tambahan yang dapat dimutasi dan melacak perubahan seperti itu rawan kesalahan, terlebih lagi karena server dan klien perlu menanganinya.

Jika Anda memiliki terlalu banyak data untuk diproses sekaligus , pertimbangkan untuk mengembalikan "daftar id" dengan semua hasil dan detail untuk sebagian daftar itu, dan berikan panggilan API untuk sumber daya multi_get / get_by_id_list.

Contoh Anda rusak. Anda seharusnya tidak memiliki objek json dengan kunci duplikat. Apa yang Anda cari adalah array dengan objek film, seperti ini:

 [
    {"name": "movie1"}, 
    {"name": "movie2"}
 ]

Pendekatan ini juga menjawab pertanyaan Anda. Anda harus mengembalikan array kosong ketika kueri tidak cocok:

[]

Di sisi lain, jika Anda mencoba untuk mendapatkan sumber daya film tertentu dengan GET api/movie/34dan film itu tidak ada, maka kembalikan 404 dengan pesan kesalahan yang sesuai (json disandikan) di dalam tubuh

Jika ini JSON, Anda harus benar-benar mempertimbangkan mengembalikan Array objek. Ini memiliki banyak keuntungan termasuk bahwa ketika Anda tidak memiliki catatan itu adalah array kosong.

Jadi, ketika Anda memiliki catatan, Anda akan kembali:

    [
        {"name": "Ghostbusters"},
        {"name": "Indiana Jones"}
    ]

Dan ketika Anda tidak memiliki catatan, Anda akan kembali:

    [

    ]

Jika Anda berhasil menjalankan operasi, tetapi tidak memiliki apa pun untuk dikembalikan, seperti peta {}kosong atau array kosong []saya lebih suka untuk menjawab dengan 204 kode respons, berikut adalah kutipan dari spesifikasi HTTP Status Code Definition :

Server telah memenuhi permintaan tetapi tidak perlu mengembalikan entitas-badan, dan mungkin ingin mengembalikan metainformation yang diperbarui. Respons MUNGKIN mencakup metainformation baru atau yang diperbarui dalam bentuk entitas-header, yang jika hadir HARUS dikaitkan dengan varian yang diminta.

Jika klien adalah agen pengguna, itu TIDAK HARUS mengubah tampilan dokumen dari yang menyebabkan permintaan untuk dikirim. Respons ini terutama dimaksudkan untuk memungkinkan input untuk tindakan terjadi tanpa menyebabkan perubahan pada tampilan dokumen aktif agen pengguna, meskipun setiap metainformasi baru atau yang diperbarui HARUS diterapkan pada dokumen yang saat ini dalam tampilan aktif agen pengguna.

Respons 204 HARUS TIDAK menyertakan badan pesan, dan karenanya selalu diakhiri oleh baris kosong pertama setelah bidang header.

Intinya, saya sarankan menggunakan 204 di aplikasi RESTful melalui HTTP ketika tidak ada yang kembali.

Ada cukup banyak pekerjaan yang dilakukan untuk membuat format API JSON standar .

Mengikuti prinsip-prinsip dalam spesifikasi itu berarti bahwa semua sumber daya yang dikembalikan harus secara efektif menjadi "koleksi" (bahkan ketika hanya satu sumber daya dimasukkan). Mengikuti ini berarti bahwa panggilan Anda untuk /v1/get/moviesakan kembali:

{
    "movies": [
        {"name": "Ghostbusters"},
        {"name": "Indiana Jones"}
    ]
}

Panggilan Anda ke /v1/get/books(yang mengembalikan nol sumber daya) akan kembali:

{
    "books": []
}

Untuk contoh spesifik Anda, saya akan merekomendasikan bahwa / v1 / get / books harus mengembalikan HTTP 200 dengan array kosong.

Jika saya membaca posting Anda dengan benar, API Anda bermaksud mengumpulkan buku. Secara metaforis, Anda memiliki rak buku untuk buku, rak DVD untuk film, dan mungkin wadah lain yang belum Anda sebutkan di sini. Karena Anda berniat mengumpulkan buku, / v1 / get / books adalah rak buku Anda. Ini berarti ada sumber daya yang valid di sana - daftar buku - yang kebetulan kosong dalam contoh spesifik Anda.

Alasan saya tidak menyarankan mengembalikan HTTP 404 dalam kasus ini adalah bahwa rak buku masih ada. Saat ini tidak ada buku di situ, tetapi masih ada rak buku. Jika itu bukan rak buku - jika API tidak bermaksud mengumpulkan buku, misalnya - maka HTTP 404 akan sesuai. Tetapi karena ada sumber daya di sana, Anda seharusnya tidak memberi sinyal bahwa tidak ada satu pun, yang dilakukan HTTP 404. Oleh karena itu, saya berpendapat bahwa 200 dengan array kosong (menandakan koleksi) lebih tepat.

Alasan saya tidak menyarankan mengembalikan HTTP 204 adalah karena ini akan menyarankan bahwa "Tidak Ada Konten" adalah keadaan umum: melakukan tindakan ini pada sumber daya ini biasanya tidak akan mengembalikan apa pun. Itu sebabnya biasanya digunakan sebagai respons terhadap permintaan DELETE, misalnya: sifat penghapusan umumnya berarti tidak ada yang tersisa untuk dikembalikan. Kasingnya mirip ketika digunakan untuk menanggapi permintaan dengan keluarga header If-Modified: Anda hanya ingin konten jika sumber daya telah berubah, tetapi tidak, jadi saya tidak akan memberikan konten apa pun kepada Anda.

Tapi saya berpendapat bahwa untuk MENDAPAT koleksi kosong tapi valid, HTTP 204 tidak masuk akal. Jika ada item dalam koleksi, maka representasi yang tepat akan menjadi array dari data itu. Oleh karena itu, ketika tidak ada data di sana (tetapi koleksi tersebut valid), representasi yang tepat adalah array kosong.

Anda benar-benar harus melakukan hanya satu dari dua hal

Entah Kembalikan 200 (OK)kode status, dan larik kosong di badan.

Atau Kembalikan 204 (NO CONTENT)kode status dan TIDAK ada badan tanggapan.

Bagi saya, opsi 2 tampaknya lebih benar secara teknis dan sejalan dengan prinsip REST dan HTTP.

Namun, opsi 1 tampaknya lebih efisien untuk klien - karena klien tidak memerlukan logika tambahan untuk membedakan antara dua kode status (sukses). Karena ia tahu bahwa ia akan selalu menerima sebuah array, ia hanya perlu memeriksa apakah tidak ada, satu, atau banyak item dan memprosesnya dengan tepat.

Saya telah melihat kedua kasus di lingkungan produksi. Yang mana yang Anda pilih tergantung pada siapa yang akan menggunakan API. Jika mereka ingin tahu mengapa daftar itu kosong atau untuk memastikan bahwa daftar itu benar-benar kosong dan tidak ada kesalahan terjadi saat mengambilnya, maka Anda harus melampirkan objek "kesalahan". Jika mereka tidak peduli, lanjutkan dengan mengembalikan daftar kosong. Saya akan menggunakan pendekatan kedua karena mencakup lebih banyak kebutuhan daripada yang pertama.

Hal pertama yang harus dipertimbangkan, karena Anda sedang membangun API RESTful, adalah mengembalikan kode respons yang sesuai. Dan kode respons yang lebih tepat untuk mengomunikasikan bahwa permintaan melalui normal, tetapi sumber daya yang diminta tidak tersedia saat ini adalah 404 terhormat.

Jika Anda mendesain API Anda sedemikian rupa sehingga selalu mengembalikan kode respons yang masuk akal, Anda bahkan mungkin tidak perlu mengembalikan tubuh ketika sumber daya tidak ditemukan. Yang mengatakan, mengembalikan tubuh, terutama yang dapat dibaca secara manusia, tidak ada salahnya.

Tidak ada "praktik terbaik" di sini, kedua contoh Anda sewenang-wenang, cukup pilih satu dan konsisten . Pengembang benci kejutan, jika /v1/get/movieskembali {}ketika tidak ada film maka kami juga berharap /v1/get/actorsuntuk kembali {}ketika tidak ada aktor.

Saya tidak berpikir jawaban yang tepat adalah yang ditandai.

Jawaban yang diberikan oleh nirth harus yang terbaik, dalam skenario REST yang sebenarnya. Respons tubuh harus kosong dan kode status http: 204; sumber daya memang ada tetapi tidak memiliki konten saat itu: kosong.

REST HTTP_Status_Codes

Saya merekomendasikan 200+ array kosong, karena menyederhanakan penanganan oleh semua klien API. 200 + array berarti "Saya mengembalikan semua data yang ada di sana". Baik untuk kode yang mengirimkan data dan kode yang memprosesnya, jumlah item tidak akan relevan.

Setiap kode status lainnya perlu didokumentasikan dengan baik dan dikirimkan dengan benar oleh server dan diproses dengan baik oleh klien, dan kita semua tahu bagaimana kemungkinan hal ini terjadi.

Ada saran untuk mengembalikan status 204+ badan kosong. Itu berarti Anda memaksa setiap satu klien status proses 204 dengan benar. Selain itu Anda memaksa mereka untuk menangani balasan non-JSON! Saya harap semua orang menyadari bahwa hanya karena permintaan mendapat jawaban, itu tidak berarti jawaban datang dari server ketika http digunakan, dan hanya memeriksa bahwa responsnya adalah JSON menangani banyak kasus tersebut.

Saya akan "Itu tergantung".

Jika nol adalah hasil yang masuk akal, maka kembalikan daftar kosong. Misalnya jika Anda ingin mendapatkan semua karyawan yang disebut "bob" di mana "tidak ada" adalah hasil yang cukup masuk akal. Jika bukan hasil yang diharapkan, kembalikan kesalahan. Misalnya mendapatkan daftar historis alamat jalan untuk orang yang Anda pekerjakan .. Mereka harus tinggal di suatu tempat sehingga tidak ada hasil yang mungkin merupakan kesalahan, bukan hanya kondisi normal.

Saya yakin Anda dapat berdebat dengan spesifik contoh saya, tetapi Anda mendapatkan ide ...

• Pertama-tama, memiliki getURL Anda tidak tenang, GET tersirat oleh metode HTTP.
• Jika Anda meminta koleksi seperti GET api/movieskembalikan 200 OKdengan array kosong [].
• Jika Anda meminta film tertentu seperti GET api/movies/1(di mana 1id) dan tidak ada, kembalikan a 404 Not Found.

Mengapa? Anda meminta sumber daya . Saat Anda meminta koleksi, sumber daya itu sendiri (koleksi) ada. Karenanya, a 404salah. Tetapi jika Anda meminta film tertentu dan tidak ada, sumber daya yang diminta tidak ada, dan Anda harus mengembalikan a 404.

Jika Anda mengembalikan JSON, lebih baik untuk selalu mengembalikan hitungan dan pesan kesalahan dan mungkin Boolean yang mengindikasikan jika ada kesalahan atau tidak, itu adalah tiga nilai meta standar saya yang dikembalikan dengan setiap daftar baris.