API TENANG mewakili tidak adanya sesuatu

Bayangkan sebuah API untuk mengidentifikasi apakah seseorang telah memilih hewan roh mereka. Mereka hanya dapat memiliki nol atau satu binatang roh.

Saat ini:

/person/{id}/selectedSpiritAnimal

ketika mereka telah memilih binatang, kembalikan http 200 dan {selectedAnimal:mole}

tetapi ketika mereka tidak memiliki pilihan itu mengembalikan http 404.

Ini membuat hewan roh saya tidak bahagia karena kami mewakili masalah domain yang valid - karena belum memilih hewan roh - sebagai kesalahan HTTP.

Plus, sebagai bisnis - erm Sprit-Animal-Hampers-R-us - kami ingin tahu ketika seseorang tidak memiliki pilihan sehingga kami dapat meminta mereka.

Apa tanggapan yang lebih baik di sini:

HTTP 200 dan {selectedAnimal:null}

atau bahkan lebih eksplisit

HTTP 200 dan {selectedAnimal:null, spiritAnimalSelected: false}

Atau lebih baik mengembalikan 404? Karena seperti this image has not yet been uploadedketika melihat gambar secara online akan menjadi 404. this person has not selected a spirit animalmungkin 404

Pertanyaan ini ini telah diusulkan sebagai duplikat tetapi pertanyaan itu membahas URL yang valid yang diminta ketika aplikasi telah dikonfigurasi untuk tidak mengizinkan perubahan yang diwakili oleh URL.

Sedangkan di sini saya melihat bagaimana seseorang mewakili sumber daya di mana ketiadaan sumber daya itu bermakna. Yaitu sah bagi klien untuk meminta URL dan jawabannya adalah Anda telah berhasil meminta sumber daya yang mewakili tidak adanya sesuatu.

Jadi ini bukan 'logika bisnis' melainkan keadaan di mana ketiadaan sesuatu memiliki makna (mungkin karena banyak rekan saya berpendapat bahwa 404 masih benar) tetapi saya tidak yakin bagaimana memetakan itu ke spek.

Sangat sulit untuk memilih jawaban. Saya telah berubah pikiran beberapa kali selama pembicaraan di sini dan yang sedang berlangsung di tempat kerja.

Hal yang menentukan bagi saya di sini adalah bahwa spesifikasi mengatakan bahwa 4xx adalah ketika klien melakukan kesalahan . Dalam hal ini klien telah diberitahu untuk mengharapkan respons dari urlSpiritAnimal yang dipilih sehingga belum keliru.

Konsensus di antara rekan-rekan saya adalah bahwa ini adalah gejala dari desain API yang buruk

Mungkin akan lebih baik jika kita hanya meminta / orang / {id} dan mengembalikan seperangkat hubungan tautan untuk orang tersebut ... maka jika Anda tidak diberi tautan / terpilihSpiritAnimal (ketika seseorang tidak memiliki pilihan) tetapi Anda sebut saja demikian maka 404 masuk akal. Atau Anda menerapkan respons sebagian dan membiarkan / orang / {id} mengembalikan dokumen yang lebih lengkap kecuali klien meminta subset data

Kode HTTP 4xx mungkin bukan pilihan yang tepat untuk skenario ini. Anda menyatakan bahwa tidak memiliki hewan roh nol adalah keadaan yang valid, dan rute API person/{id}/selectedSpiritAnimalakan menjelaskan apakah orang idtersebut memiliki atau tidak.

Respons HTTP 4xx dicadangkan untuk situasi ketika klien telah melakukan sesuatu yang salah dalam permintaan (lihat arsip spesifikasi asli w3 ). Tetapi klien membuat permintaan yang valid, apakah seseorang idmemiliki hewan roh atau tidak .

Jadi saya condong ke solusi kedua menggunakan tubuh JSON yang diformat dengan baik dalam respon dan kode HTTP 2xx.

Sekarang jika Anda mendapatkan permintaan seperti itu dan ternyata orang iditu tidak ada, kode 4xx lebih masuk akal.

Izinkan saya memperkenalkan Anda kepada Model Kematangan Richardson .

Masalah Anda adalah bahwa Anda mewakili dua sumber daya sebagai satu, di mana Anda harus benar-benar memiliki dua sumber daya yang memiliki hubungan yang ditunjukkan oleh hypermedia. Menggunakan hypermedia untuk menggambarkan hubungan adalah level 3 Rest yang mulia.

Orang Anda harus hidup di bawah URI /person/{id}dan hewan itu harus hidup di bawah /spiritanimal/{id}. Orang tersebut harus menunjukkan bahwa ia memiliki hewan roh dengan menggunakan tautan ke hewan tersebut.

Mari kita bayangkan seseorang bernama Bob, yang memiliki id 123 dan binatang roh Unicorn.

GET /person/123

akan kembali;

{
  "name": "Bob",
  "links": [
    {
      "rel": "spiritanimal",
      "uri": "/spiritanimals/789"
    }
  ]
}

Sekarang siapa pun yang membaca orang 123 akan tahu bahwa mereka memiliki binatang roh, dan memiliki URI di mana mereka dapat memperoleh lebih banyak informasi tentangnya.

GET /spitiranimal/789

mungkin kembali

{
  "type": "Unicorn"
}

Sekarang mari kita bayangkan seseorang bernama Fred, yang memiliki id 456 dan tidak memiliki binatang roh.

GET /person/456

akan kembali;

{
  "name": "Fred",
  "links": [
  ]
}

Sekarang siapa pun yang membaca orang 456 akan tahu bahwa mereka tidak memiliki binatang roh, karena tidak ada tautan. Tidak perlu menggunakan kode status HTTP untuk mewakili kurangnya hubungan.

Ini adalah url yang tepat untuk mendapatkan hewan roh; oleh karena itu, kesalahan 404 tidak pantas. 404 adalah untuk merepresentasikan masalah teknis, bukan masalah logika.

Solusi yang tepat adalah mengembalikan http 200 dan {"selectedAnimal": null}

Anda harus memiliki metode web terpisah/person/{id}/hasSelectedSpiritAnimal yang mengembalikan {"isSpiritAnimalSelected": false}. Di balik layar, mungkin atau mungkin tidak membuat panggilan metode yang sama, hanya mengembalikan false jika null, tetapi itu terserah dia yang memutuskan, bukan kode pengkonsumsi.

Lebih baik untuk menghindari menggabungkan permintaan yang terpisah menjadi satu metode web tanpa alasan kuat untuk melakukannya, bahkan jika permintaan itu terkait erat.

Apa yang diwakili oleh titik akhir Anda bukan hanya binatang; itu binatang atau kurang. Ini nilai terbaik yang diwakili oleh Optional/ Maybe/Nullable / dll.

Jadi nilai yang sah (seperti pada 200 OK) mungkin:

• {'animal': <some animal>, 'selected': true}
• {'animal': null, 'selected': false}

Saya bisa membayangkan bahwa DELETEmetode, ketika diterapkan ke titik akhir, dapat diatur 'selected'kefalse lagi, yaitu, unset hewan yang dipilih.

Anda dapat, tentu saja, menjatuhkan 'selected'kunci di sini, itu hanya ditampilkan untuk kejelasan; string vs nullsudah cukup untuk membedakannya.

Anda harus menggunakan 404.

Kode status 404 (Tidak Ditemukan) menunjukkan bahwa server asal tidak menemukan representasi saat ini untuk sumber daya target

RFC7231

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

"mole"

HTTP/1.1 404 Not Found
Content-Type: text/plain
Date: Mon, 25 Sep 2017 00:00:00 GMT

this person has not selected a spirit animal

Karena Anda membuat antarmuka pemrograman, bukan antarmuka manusia, teks 404 adalah opsional.

Saya lebih suka ini karena saya lebih suka protokol standar sebanyak mungkin. HTTP memiliki cara untuk merepresentasikan non-keberadaan, dan itulah yang akan saya gunakan.

EDIT: Misalkan Anda menambahkan fitur di mana pengguna dapat memilih apakah akan membagikan hewan roh mereka, dan seseorang tidak membagikannya. Apakah Anda akan mengembalikan 200 OK null, atau 200 OK "Unauthorized? Atau apakah Anda akan menggunakan standar 401 Unauthorized / 403 Forbidden? Ini sepertinya analog dengan tidak memilih yang pertama kali.

Atau, jika Anda ingin menggunakan 200 OK + JSON, Anda harus kembali null.

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

"mole"

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

null

Jaga kebersihan. Buat lebih banyak pembungkus hanya jika perlu.