Apakah ini praktik yang baik untuk membuat daftar nilai tanggapan API sebagai kamus?

Saya memiliki titik akhir API yang mengembalikan beberapa statistik. Saat ini responsnya seperti:

Pilihan 1:

{
    "stats": [
                {
                    "name": "some-stats-key1",
                    "value": 10
                },
                {
                    "name": "some-stats-key2",
                    "value": 20
                }
            ],
    ... other keys
}

Tapi ini terlihat agak rumit dan saya harus membuatnya seperti apa:

Pilihan 2:

{
    "stats": {
                "some-stats-key1": 10,
                "some-stats-key2": 20
            }
    ... other keys
}

Saya mengerti bahwa Opsi 1 lebih mudah diperpanjang, tetapi kurang nyaman bagi pengguna. Apa masalah lain yang bisa saya hadapi menggunakan salah satu opsi ini? Atau haruskah saya membuat solusi hybrid seperti:

Opsi 3:

{
    "stats": {
                "some-stats-key1": {
                                        "name": "some-stats-key1",
                                        "value": 10
                                    },
                "some-stats-key2": {
                                        "name": "some-stats-key2",
                                        "value": 20
                                    },
            },
    ... other keys
}

Kunci "some-stats-key1" dan "some-stats-key2" hanyalah nilai internal dan diharapkan pengguna API akan memetakannya menjadi nama yang dapat dibaca menggunakan dokumentasi. Semua kunci unik.

Urutan "statistik" tidak penting.

Kasus penggunaan yang umum adalah hanya untuk mendapatkan semua statistik, mencocokkan kunci dengan nama yang dapat dibaca dan ditampilkan sebagai tabel di halaman web. Tetapi saat ini saya tidak bisa mengatakan jika tidak ada yang akan membutuhkan hanya sebagian dari statistik nanti.

Apakah ada praktik terbaik untuk masalah ini?

Saya akan memilih opsi 2. Jika konsumen API akan mengonversi some-stats-key1menjadi sesuatu yang dapat dibaca, itu mungkin berarti ia memiliki daftar nilai yang ia minati (katakan, some-stats-key1dan some-stats-key3), dan akan beralih ke daftar itu. Dengan memilih objek JSON, itu akan dideserialisasi sebagai kamus / peta yang menyediakan pencarian yang nyaman bagi konsumen API.

Ini akan lebih rumit dengan opsi 1, di mana konsumen perlu untuk mengulangi lebih dari array JSON, atau pra-buat kamus mereka sendiri dengan kunci yang menarik.

Opsi 3 agak terlalu bertele-tele bagi saya, duplikasi nama-nama kunci tidak menarik bagi saya.

Jika ekstensibilitas menjadi perhatian, Anda selalu dapat menerbitkan v2 API Anda yang mengembalikan sesuatu seperti

"stats": {
    "some-stats-key1": { "value": 10, "error-margin": 0.1 },
    "some-stats-key2": { "value": 20, "error-margin": 0.2 }
}

dan simpan v1 untuk kompatibilitas ke belakang. Mempertahankan kompatibilitas mundur dalam satu versi API dapat menjadi PITA nyata jika Anda tidak memiliki kontrol penuh atas bagaimana API dikonsumsi. Saya telah melihat konsumsi API saya 'break' ketika saya baru saja menambahkan pasangan nilai kunci tambahan (opsional) (yaitu tidak mengubah struktur).

Kedua opsi memiliki keunggulan Daftar vs. Peta klasik.

1) Daftar memungkinkan entri duplikat dan mempertahankan ketertiban. Jika fitur-fitur ini penting, gunakan Daftar, meskipun itu clunkier.

2) Peta tidak memungkinkan duplikat. Mempertahankan pesanan dimungkinkan dengan sedikit kerja ekstra. Keuntungan besar adalah kesederhanaan dalam format data, dan mencari elemen tertentu sepele.

Pilihan default saya selalu adalah Peta yang lebih sederhana, tetapi YMMV.

Ketika saya mendapatkan data dari API, saya selalu memeriksa bahwa semuanya seperti yang saya harapkan. Jadi upaya saya untuk memproses data Anda terdiri dari verifikasi, dan pemrosesan yang sebenarnya.

Dalam kasus 1 saya harus memeriksa: a. Ada sebuah array. b. Semua item dalam array adalah kamus. c. Setiap kamus memiliki "nama" kunci. d. Semua nilai untuk kunci "nama" unik.

Dalam kasus 3 saya harus memeriksa: a. Ada kamus. b. Semua nilai dalam kamus adalah kamus. c. Setiap kamus memiliki "nama" kunci dengan nilai yang cocok dengan kunci di kamus luar. Sedikit lebih baik.

Dalam kasus 2 saya harus memeriksa: a. Ada kamus.

(Tentu saja saya harus memeriksa nilainya juga). Jadi kasing 2 Anda membutuhkan paling sedikit pemeriksaan di pihak saya. Saya benar-benar mendapatkan struktur data yang langsung dapat digunakan.

Satu-satunya masalah dengan 2 adalah tidak dapat diperpanjang. Jadi, alih-alih mengirim nilai sebagai angka, Anda dapat mengirim {value: 10} yang kemudian dapat diperluas dengan cara yang kompatibel ke belakang.

Redundansi itu buruk. Satu-satunya hal yang redundansi capai adalah membuat saya menulis lebih banyak kode, dan memaksa saya untuk berpikir tentang apa yang harus saya lakukan jika bit yang berlebihan tidak setuju. Versi 2 tidak memiliki redundansi.

Karena Anda meminta praktik yang baik untuk desain API:

• Saya tidak pernah mengembalikan respons api yang berisi objek di tingkat atas. Semua panggilan layanan mengembalikan set (sebagai array), dan set itu berisi elemen (sebagai instance objek.) Jumlah objek yang dikembalikan dalam array tidak relevan dengan server. Jika klien perlu menentukan dari jumlah barang yang dikembalikan dalam respons, beban itu adalah tanggung jawab klien. Jika satu item diharapkan, itu akan dikembalikan sebagai satu set unit
• Ketika saya merancang api, saya tidak berasumsi untuk mengetahui teknologi spesifik apa yang akan digunakan klien api saya untuk mengonsumsi api tersebut, bahkan ketika saya tahu teknologi spesifik apa yang paling mungkin mereka gunakan. Tanggung jawab saya adalah untuk mengkomunikasikan representasi domain saya secara konsisten ke semua konsumen, tidak nyaman untuk konsumen tertentu.
• Jika ada opsi struktural untuk memungkinkan tanggapan dikomposisi, struktur ini mengambil prioritas di atas opsi yang tidak
• Saya berusaha keras untuk menghindari membuat representasi yang memiliki struktur tak terduga.
• Jika struktur representasi dapat diprediksi, maka semua contoh di dalam rangkaian respons harus dari representasi yang sama dan rangkaian respons harus konsisten secara internal.

Jadi, mengingat struktur yang Anda usulkan, struktur yang akan saya terapkan akan terlihat mirip dengan ini

[
   { /* returns only the 'common' metrics */
      "stats": [
                  {"key":"some-metric1","value":10},
                  {"key":"some-metric2","value":20}
               ]
   },
   { /* returns an optional metric in addition to the "common" metrics */
      "stats": [
                  {"key":"some-metric1","value":15},
                  {"key":"some-metric2","value":5},
                  {"key":"some-optional-metric", "value":42}
               ]
   },
   { /*returns the 'common' metrics as well as 2 candidates for "foo-bar" */
      "stats": [
                  {"key":"some-metric1", "value": 5},
                  {"key":"some-metric2", "value": 10},
                  {"key":"foo-bar-candidate", "value": 7},
                  {"key":"foo-bar-candidate", "value": 11}
               ]
   }
]